setup-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

setup-context

上下文初始化（setup-context）

Take the user from

pip install nao-core

to a synced project with a starter

RULES.md

Be brief. One batch of questions, then act. Don't ping-pong.

Scope ceiling: ≤100 tables. Above that, sync gets slow and per-table context budget gets thin. 20 is a great target.

引导用户完成从

pip install nao-core

到项目同步并生成初始

RULES.md

的全流程。

简洁高效：一次性提出所有问题，然后执行操作，避免来回沟通。

范围上限：≤100张表：超过这个数量，同步速度会变慢，且单表上下文预算会不足。建议目标为20张表。

Step 1 — Ask everything in one round

步骤1 — 一次性收集所有信息

Send a single message asking for:

Warehouse + auth — type (BigQuery / Snowflake / Postgres / Redshift / DuckDB / Databricks / Athena / ClickHouse / Fabric / MSSQL / MySQL / Trino), and the auth credentials they have on hand. Tell them you'll fetch the exact field names from the nao docs once they pick a type.
Scope — which tables. Two valid shapes:
- Broad — gold/marts across multiple domains (exec / cross-functional agents).
- Deep — silver + gold for one domain (team-specific agents).
Extra context — dbt / ETL / BI repos, Notion, internal docs. Ask for the SSH git URL of each repo (e.g.
```
git@github.com:org/repo.git
```
) — sync clones them. No local paths.
LLM — provider + model. Key comes later (Step 5).

发送一条消息，询问以下内容：

数据仓库及认证信息：仓库类型（BigQuery / Snowflake / Postgres / Redshift / DuckDB / Databricks / Athena / ClickHouse / Fabric / MSSQL / MySQL / Trino），以及用户手头的认证凭据。告知用户一旦选定类型，你将从nao文档中获取具体的字段名称。
范围：需要同步的表。有两种有效范围类型：
- 广度覆盖：跨多个领域的gold/marts层表（供高管/跨职能agent使用）。
- 深度聚焦：单个领域的silver+gold层表（供特定团队agent使用）。
额外上下文：dbt / ETL / BI代码仓库、Notion文档、内部文档。要求提供每个仓库的SSH git地址（例如
```
git@github.com:org/repo.git
```
）——同步时会克隆这些仓库。不接受本地路径。
LLM：提供商及模型。密钥将在后续步骤（步骤5）中配置。

Step 2 — Look up warehouse fields, write

nao_config.yaml

, run

nao init

步骤2 — 查询仓库字段，编写

nao_config.yaml

，执行

nao init

Fetch the warehouse-specific config from docs.getnao.io/nao-agent/context-builder/databases. Each warehouse has its own required and optional fields (e.g. BigQuery needs
```
project_id
```
+
```
dataset_id
```
(optional); Snowflake needs
```
account_id
```
+
```
warehouse
```
+
```
schema_name
```
(optional); Postgres needs
```
host
```
+
```
port
```
+
```
database
```
+
```
schema_name
```
(optional). Ask the user for any required field you don't already have.
Write
nao_config.yaml
from the answers (skeleton in appendix below).
Run
nao init
— it detects the existing yaml and offers to update; confirm. Folder scaffold gets created. Say "no" to optional providers (skills / MCPs / Notion / Slack); edit the yaml directly afterwards if needed.

Print a summary of
nao_config.yaml
to the user before going further. Format example:

nao_config.yaml summary
  • project: <name>
  • warehouse: BigQuery (project=<id>, dataset=<id>, auth=service-account)
  • scope: include=["analytics.fct_*", "analytics.dim_*"], exclude=[]
  • templates: [columns, preview, description]
  • repos: company-dbt (git@github.com:org/company-dbt.git)
  • llm: anthropic / claude-sonnet-4-7 (key via ${ANTHROPIC_API_KEY})

Ask the user to confirm before continuing. This is the last cheap chance to catch a wrong project, a misspelled dataset, or a missing repo.

获取仓库专属配置：从docs.getnao.io/nao-agent/context-builder/databases获取。每个仓库都有自己的必填和可选字段（例如BigQuery需要
```
project_id
```
+
```
dataset_id
```
（可选）；Snowflake需要
```
account_id
```
+
```
warehouse
```
+
```
schema_name
```
（可选）；Postgres需要
```
host
```
+
```
port
```
+
```
database
```
+
```
schema_name
```
（可选））。向用户索要任何你尚未获取的必填字段。
编写
nao_config.yaml
：根据用户提供的信息编写（参考下方附录中的模板）。
执行
nao init
：该命令会检测已存在的yaml文件并提供更新选项；确认更新。系统会创建文件夹结构。对可选提供商（skills / MCPs / Notion / Slack）选择“否”；如有需要，后续可直接编辑yaml文件。

向用户展示
nao_config.yaml
的摘要，然后再继续操作。格式示例：

nao_config.yaml summary
  • project: <name>
  • warehouse: BigQuery (project=<id>, dataset=<id>, auth=service-account)
  • scope: include=["analytics.fct_*", "analytics.dim_*"], exclude=[]
  • templates: [columns, preview, description]
  • repos: company-dbt (git@github.com:org/company-dbt.git)
  • llm: anthropic / claude-sonnet-4-7 (key via ${ANTHROPIC_API_KEY})

请用户确认后再继续。这是最后一个可以低成本发现项目错误、数据集拼写错误或仓库缺失的机会。

Database

templates

field

数据库

templates

字段

Per database in the yaml, set:

yaml

templates: [columns, preview, description]

That's the set this skill ships. Other values are valid per-warehouse (

how_to_use

profiling

ai_summary

, and

indexes

for ClickHouse) — see the docs link above — but stick to

[columns, preview, description]

unless the user specifically asks otherwise.

Don't use
accessors
— deprecated (renamed to

templates

nao init

creates:

nao_config.yaml

, empty

RULES.md

.naoignore

, and folders

databases/

repos/

docs/

semantics/

queries/

tests/

agent/{tools,mcps,skills}/

针对yaml中的每个数据库，设置：

yaml

templates: [columns, preview, description]

这是本技能默认的配置集合。根据仓库类型还可以使用其他有效值（例如ClickHouse支持

how_to_use

、

profiling

、

ai_summary

和

indexes

）——可查看上方的文档链接——但除非用户特别要求，否则请坚持使用

[columns, preview, description]

。

请勿使用
accessors
——已废弃（已更名为

templates

）。

nao init

会创建以下文件和文件夹：

nao_config.yaml

、空的

RULES.md

、

.naoignore

，以及

databases/

、

repos/

、

docs/

、

semantics/

、

queries/

、

tests/

、

agent/{tools,mcps,skills}/

文件夹。

Step 3 —

nao sync

步骤3 — 执行

nao sync

After the user confirms the summary in Step 2:

bash

cd <project>   # where nao_config.yaml lives — every nao command runs from here
nao sync

Common failures: auth (fix yaml), tables not found (check schema casing), permission denied (grant read access), repo missing (fix

repos:

block, confirm SSH key). Don't move on until sync is clean.

用户确认步骤2中的摘要后：

bash

cd <project>   # 进入nao_config.yaml所在的目录——所有nao命令都需在此目录下执行
nao sync

常见失败原因：认证错误（修改yaml文件）、表未找到（检查 schema 大小写）、权限不足（授予读取权限）、仓库缺失（修复

repos:

块，确认SSH密钥）。必须确保同步成功后再继续。

Step 4 — Generate

RULES.md

(no confirmation)

步骤4 — 生成

RULES.md

（无需确认）

Hand off directly to

write-context-rules

. Don't ask.

直接调用

write-context-rules

功能，无需询问用户。

Step 5 — Wire up the LLM key

步骤5 — 配置LLM密钥

The key lives in

nao_config.yaml

. Two safe options:

Preferred: env-var ref. Write
```
api_key: ${ANTHROPIC_API_KEY}
```
; tell the user to export the key in their shell.
If they insist on a literal: tell them to edit the yaml themselves and add it to
```
.gitignore
```
. Never ask them to paste a key into chat.

Then

nao debug

to confirm.

密钥存储在

nao_config.yaml

中。有两种安全配置方式：

推荐方式：环境变量引用。写入
```
api_key: ${ANTHROPIC_API_KEY}
```
；告知用户在终端中导出该密钥。
若用户坚持明文存储：告知用户自行编辑yaml文件并将其添加到
```
.gitignore
```
中。绝对不要让用户在聊天框中粘贴密钥。

然后执行

nao debug

确认配置生效。

Known issue —

AI_APICallError: Not Found

已知问题 —

AI_APICallError: Not Found

nao chat

nao debug

nao test

fails with that error and the URL is

https://api.anthropic.com/messages

(no

/v1/

), the parent agentic CLI (Claude Code, Cursor, Codex) is leaking

ANTHROPIC_BASE_URL

into the child env. Fix:

bash

unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY
nao chat   # or debug / test

Regular human terminals aren't affected.

如果

nao chat

nao debug

nao test

执行失败并返回该错误，且请求URL为

https://api.anthropic.com/messages

（缺少

/v1/

），则是父代理CLI（Claude Code、Cursor、Codex）将

ANTHROPIC_BASE_URL

泄露到了子环境中。修复方法：

bash

unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY
nao chat   # 或debug / test

普通终端不会出现此问题。

Step 6 — Recommend next steps

步骤6 — 推荐后续操作

Smoke test:
```
nao chat
```
, ask 3-5 real questions.
Review
```
RULES.md
```
for wrong inferences.
Pick a next skill:
```
write-context-rules
```
(refine),
```
create-context-tests
```
(benchmark),
```
audit-context
```
(anytime),
```
add-semantic-layer
```
(only after tests reveal metric-reliability gaps).

冒烟测试：执行
```
nao chat
```
，提出3-5个实际问题。
审查
```
RULES.md
```
，修正错误推断。
选择后续技能：
```
write-context-rules
```
（优化规则）、
```
create-context-tests
```
（基准测试）、
```
audit-context
```
（随时可用）、
```
add-semantic-layer
```
（仅在测试发现指标可靠性问题后使用）。

Guardrails

约束规则

cd
into the project directory before any
nao
command.
Cap at ~100 tables.
One batch of questions. Look up warehouse-specific fields from the docs, don't keep pinging the user.
Run
nao init
non-interactively with the yaml pre-written.

Use
templates: [columns, preview, description]
. Don't use

accessors

Repos: SSH git URLs only. No local paths in the
```
repos:
```
block.
Print the
nao_config.yaml
summary and get user confirmation before
```
nao sync
```
.
Never have the user paste their LLM key into chat.
Don't ask before invoking
write-context-rules
— just hand off.

执行任何nao命令前，请先
cd
到项目目录。
表数量上限约为100张。
一次性提出所有问题。从文档中查询仓库专属字段，不要反复询问用户。
使用预编写的yaml文件非交互式执行
nao init
。

使用
templates: [columns, preview, description]
。请勿使用

accessors

。

仓库仅支持SSH git地址。
```
repos:
```
块中不允许使用本地路径。
打印
nao_config.yaml
摘要，并在执行
```
nao sync
```
前获得用户确认。
绝对不要让用户在聊天框中粘贴LLM密钥。
调用
write-context-rules
前无需询问——直接跳转执行。

Appendix —

nao_config.yaml

skeleton (BigQuery example)

附录 —

nao_config.yaml

模板（BigQuery示例）

Use this shape and adapt the

databases:

block per warehouse — see docs.getnao.io/nao-agent/context-builder/databases for the exact required/optional fields for Snowflake, Postgres, Redshift, Databricks, Athena, ClickHouse, Fabric, MSSQL, MySQL, Trino.

yaml

project_name: <project>

databases:
    - type: bigquery
      name: <connection-name>
      project_id: <gcp-project-id>
      dataset_id: <dataset>
      credentials_path: /path/to/service-account.json # or `sso: true`
      include: ['<dataset_pattern>.<table_pattern>'] # e.g. "analytics.fct_*" - use '*' as multiple patterns
      exclude: ['<pattern>']
      templates: [columns, preview, description]

llm:
    provider: anthropic # openai | bedrock | azure | gemini | mistral | ollama
    api_key: ${ANTHROPIC_API_KEY}

repos:
    - name: <repo-name>
      url: git@github.com:<org>/<repo>.git # SSH only

使用此模板，并根据仓库类型调整

databases:

块——请查看docs.getnao.io/nao-agent/context-builder/databases获取Snowflake、Postgres、Redshift、Databricks、Athena、ClickHouse、Fabric、MSSQL、MySQL、Trino的确切必填/可选字段。

yaml

project_name: <project>

databases:
    - type: bigquery
      name: <connection-name>
      project_id: <gcp-project-id>
      dataset_id: <dataset>
      credentials_path: /path/to/service-account.json # 或`sso: true`
      include: ['<dataset_pattern>.<table_pattern>'] # 例如 "analytics.fct_*" - 使用'*'匹配多个模式
      exclude: ['<pattern>']
      templates: [columns, preview, description]

llm:
    provider: anthropic # openai | bedrock | azure | gemini | mistral | ollama
    api_key: ${ANTHROPIC_API_KEY}

repos:
    - name: <repo-name>
      url: git@github.com:<org>/<repo>.git # 仅支持SSH

setup-context

Original

Translation

setup-context

上下文初始化（setup-context）

Step 1 — Ask everything in one round

步骤1 — 一次性收集所有信息

Step 2 — Look up warehouse fields, write
`nao_config.yaml`
, run
`nao init`

步骤2 — 查询仓库字段，编写
`nao_config.yaml`
，执行
`nao init`

Database
`templates`
field

数据库
`templates`
字段

Step 3 —
`nao sync`

步骤3 — 执行
`nao sync`

Step 4 — Generate
`RULES.md`
(no confirmation)

步骤4 — 生成
`RULES.md`
（无需确认）

Step 5 — Wire up the LLM key

步骤5 — 配置LLM密钥

Known issue —
`AI_APICallError: Not Found`

已知问题 —
`AI_APICallError: Not Found`

Step 6 — Recommend next steps

步骤6 — 推荐后续操作

Guardrails

约束规则

Appendix —
`nao_config.yaml`
skeleton (BigQuery example)

附录 —
`nao_config.yaml`
模板（BigQuery示例）

setup-context

Original

Translation

setup-context

上下文初始化（setup-context）

Step 1 — Ask everything in one round

步骤1 — 一次性收集所有信息

Step 2 — Look up warehouse fields, write nao_config.yaml, run nao init

步骤2 — 查询仓库字段，编写nao_config.yaml，执行nao init

Database templates field

数据库templates字段

Step 3 — nao sync

步骤3 — 执行nao sync

Step 4 — Generate RULES.md (no confirmation)

步骤4 — 生成RULES.md（无需确认）

Step 5 — Wire up the LLM key

步骤5 — 配置LLM密钥

Known issue — AI_APICallError: Not Found

已知问题 — AI_APICallError: Not Found

Step 6 — Recommend next steps

步骤6 — 推荐后续操作

Guardrails

约束规则

Appendix — nao_config.yaml skeleton (BigQuery example)

附录 — nao_config.yaml模板（BigQuery示例）

Step 2 — Look up warehouse fields, write
`nao_config.yaml`
, run
`nao init`

步骤2 — 查询仓库字段，编写
`nao_config.yaml`
，执行
`nao init`

Database
`templates`
field

数据库
`templates`
字段

Step 3 —
`nao sync`

步骤3 — 执行
`nao sync`

Step 4 — Generate
`RULES.md`
(no confirmation)

步骤4 — 生成
`RULES.md`
（无需确认）

Known issue —
`AI_APICallError: Not Found`

已知问题 —
`AI_APICallError: Not Found`

Appendix —
`nao_config.yaml`
skeleton (BigQuery example)

附录 —
`nao_config.yaml`
模板（BigQuery示例）