> ## Agent Instructions
>
> Base URL: https://api.anysite.io
> Authentication: send the `access-token` header. Do NOT use `Authorization: Bearer`.
> Full endpoint catalog: https://app.anysite.io/docs
# 数据库发现与目录

自动发现数据库结构，用 LLM 生成描述并丰富信息，浏览已保存的目录

## 概述

在加载或查询数据之前，了解数据库中已有的内容会很有帮助。**发现（discovery）**命令会对已连接的
SQLite、PostgreSQL 或 ClickHouse 连接进行内省，并构建结构化目录 — 表、列、类型、索引、外键、
行数和示例数据。还可以选择用 LLM 生成的描述来丰富目录，以便立即获得上下文信息。

发现得到的目录会本地保存在 `~/.anysite/catalogs/<connection>.yaml`，可以随时浏览 — 这对需要数据库
上下文但又不想手写文档的 AI 代理很有用。

## 发现数据库结构

```bash
anysite db discover mydb
```

这会对数据库进行内省，并输出：

- **表** 及其行数
- **列** — 名称、类型、是否可空、默认值、主键
- **索引** — 名称、列、是否唯一
- **外键** — 源列和目标列
- **示例数据** — 每张表的少量行（默认 1 行；见 `--sample-rows`）
- **只读状态** — 自动检测（PostgreSQL 副本、只读文件系统、ClickHouse 的 `readonly` 设置）

结果会作为目录保存以供后续参考。

> 
  发现功能支持 SQLite（通过 PRAGMA）、PostgreSQL（通过 `information_schema` 和 `pg_catalog`）和
  ClickHouse（通过 `system.tables` 和 `system.columns`）。ClickHouse 不支持外键，因此对它进行外键
  发现会返回空结果。

## LLM 增强

```bash
anysite db discover mydb --with-llm
```

> 
  需要 `llm` 可选依赖包：`pip install "anysite-cli[llm]"`，并配置好 LLM 提供商
  （`anysite llm setup`）。

LLM 增强会添加四层上下文信息：

| 层级 | 生成内容 |
|-------|-------------------|
| **表描述** | 每张表的用途和角色 |
| **列描述** | 每一列的语义含义 |
| **隐式关系** | 除已声明的外键之外，基于命名模式的检测（例如 `user_id` → `users.id`） |
| **数据库描述** | 数据库整体结构和用途的总结 |

`--provider` 和 `--model` 会为本次运行覆盖默认的 LLM 提供商/模型；`--no-cache` 会跳过 LLM 响应缓存。

## 过滤表

```bash
# Discover specific tables only
anysite db discover mydb --tables users,posts,comments

# Exclude internal tables
anysite db discover mydb --exclude-tables _migrations,django_session

# Control sample data rows (default: 1)
anysite db discover mydb --sample-rows 10
```

### 发现选项

| 选项 | 描述 | 默认值 |
|--------|-------------|---------|
| `--tables` | 要包含的表名列表（逗号分隔） | 所有表 |
| `--exclude-tables` | 要跳过的表名列表（逗号分隔） | 无 |
| `--sample-rows` | 每张表的示例行数 | `1` |
| `--with-llm` | 使用 LLM 生成的描述进行增强 | 关闭 |
| `--provider` | LLM 提供商覆盖（`openai`/`anthropic`） | 已配置的默认值 |
| `--model` | LLM 模型覆盖 | 已配置的默认值 |
| `--no-cache` | 跳过 LLM 响应缓存 | 关闭 |
| `--quiet`, `-q` | 最简化的控制台输出 | 关闭 |

## 浏览已保存的目录

```bash
# List all saved catalogs
anysite db catalog

# View a specific catalog
anysite db catalog mydb

# View a single table from the catalog
anysite db catalog mydb --table users

# JSON output (for agents and scripts)
anysite db catalog mydb --json
```

> 
  使用 `anysite db catalog mydb --json` 将数据库上下文注入 AI 代理。该 JSON 包含所有表、列、
  关系和 LLM 生成的描述。

## 命令参考

| 命令 | 描述 |
|---------|-------------|
| `anysite db discover <conn>` | 发现并保存数据库结构 |
| `anysite db discover <conn> --with-llm` | 使用 LLM 生成的描述进行发现 |
| `anysite db discover <conn> --tables t1,t2` | 只发现指定的表 |
| `anysite db discover <conn> --exclude-tables t1` | 在发现中排除指定表 |
| `anysite db discover <conn> --sample-rows N` | 控制示例数据行数 |
| `anysite db catalog` | 列出所有已保存的目录 |
| `anysite db catalog <conn>` | 查看某个连接已保存的目录 |
| `anysite db catalog <conn> --table <name>` | 查看目录中的某张表 |
| `anysite db catalog <conn> --json` | 以 JSON 形式输出目录 |

## 后续步骤

  
#### Database Operations

    对数据库进行插入、查询和同步操作
  
  
#### Agent Protocol

    面向 AI 代理集成的结构化 JSON 输出