> ## 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
# 代理协议

面向 AI 代理集成的结构化 JSON 输出、退出码、错误码和两级发现机制

## 概述

Anysite CLI 会自动检测标准输出是否处于管道或子进程中（非 TTY），并在这种情况下将大多数命令切换为
结构化 JSON 输出。脚本和 AI 代理无需任何标志或配置。

| 场景 | 默认输出 | 覆盖方式 |
|---------|-----------------|----------|
| 终端（TTY） | 人类可读的富文本 | 在命令上加 `--json`，强制输出 JSON |
| 管道 / 子进程（非 TTY） | JSON | 使用全局标志 `--human`，强制输出人类可读文本 |

```bash
# In terminal — human-readable output (default)
anysite config list

# In terminal — force JSON output
anysite config list --json

# In pipe — JSON automatically
anysite config list | jq '.result'

# In pipe — force human output
anysite config list --human | less
```

`--non-interactive` 会禁用交互式提示（确认、选择）。只要 stdin 不是 TTY，它就会自动启用。

> 
  `--json` 是按命令单独定义的，不是全局标志 — 见
  [Installation](/docs/cli/installation?lang=zh#global-options)。运行
  `anysite <command> --help` 可以检查某个命令是否有 `--json` 标志。

## JSON 信封

`config`、`db`、`dataset`、`llm`、`auth status`、`schema update` 和 `changelog` 下的大多数子命令都会将
JSON 输出包装在一个信封结构中：

**成功：**
```json
{
  "ok": true,
  "result": { "...": "command-specific data" },
  "hints": [{"action": "Next step", "command": "anysite ..."}],
  "meta": {"version": "0.3.23", "command": "anysite db add"}
}
```

**失败：**
```json
{
  "ok": false,
  "error": {
    "code": "CONNECTION_NOT_FOUND",
    "message": "Connection 'mydb' not found",
    "retryable": false,
    "suggestions": ["Add one with: anysite db add <name> --type sqlite --path ./data.db"]
  },
  "meta": {"version": "0.3.23"}
}
```

示例：添加数据库连接会返回该信封结构，其中 `hints` 给出后续命令建议：

```bash
anysite db add local --type sqlite --path ./data.db --json | jq '.hints'
```

> 
  `anysite api` 和 `anysite describe`（列表模式和单端点模式）是两个例外：它们会以所选的
  `--format` 直接打印 API/模式数据，而不是 `{ok, result, ...}` 信封，并且 `anysite api` 完全没有
  `--json` 标志。只有 `anysite describe --search` 使用该信封。只在上面列出的信封命令上检查 `ok`。

在信封结构适用的地方：通过 `ok` 判断成功/失败，通过 `error.code` 做程序化处理，通过
`error.retryable` 决定是否重试，通过 `error.suggestions` / `hints` 获取后续步骤建议。

## 退出码

| 代码 | 含义 | 触发场景 |
|------|---------|------|
| 0 | 成功 | 命令成功完成 |
| 1 | 一般错误 | 未处理的错误、服务器错误 |
| 2 | 用法错误 | 参数无效、缺少必填参数 |
| 3 | 认证失败 | API 密钥无效或已过期 |
| 4 | 资源未找到 | 端点、连接或数据源未找到 |
| 5 | 网络错误 | 连接失败、超时、速率限制 |

```bash
anysite api /api/linkedin/user user=satyanadella
case $? in
  0) echo "Success" ;;
  3) echo "Check your API key" ;;
  5) echo "Network issue, retrying..." ;;
  *) echo "Error: exit code $?" ;;
esac
```

## 错误码

  
#### API Errors

    | 错误码 | 退出码 | 可重试 | 触发条件 |
    |------------|-----------|-----------|---------|
    | `AUTH_FAILED` | 3 | 否 | API 密钥无效或已过期 |
    | `RATE_LIMIT` | 5 | 是 | 请求过多 |
    | `NOT_FOUND` | 4 | 否 | 资源未找到 |
    | `VALIDATION_ERROR` | 2 | 否 | 输入参数有误 |
    | `SERVER_ERROR` | 1 | 是 | API 服务器错误（5xx） |
    | `NETWORK_ERROR` | 5 | 是 | 连接失败 |
    | `TIMEOUT` | 5 | 是 | 请求超时 |
  
  
#### Database Errors

    | 错误码 | 退出码 | 可重试 | 触发条件 |
    |------------|-----------|-----------|---------|
    | `CONNECTION_NOT_FOUND` | 4 | 否 | 数据库连接未配置 |
  
  
#### Dataset Errors

    | 错误码 | 退出码 | 可重试 | 触发条件 |
    |------------|-----------|-----------|---------|
    | `DATASET_ERROR` | 1 | 否 | 数据集操作失败 |
    | `CIRCULAR_DEPENDENCY` | 1 | 否 | 多个数据源之间形成循环引用 |
    | `SOURCE_NOT_FOUND` | 4 | 否 | 在数据集配置中未找到数据源 |
  
  
#### LLM Errors

    | 错误码 | 退出码 | 可重试 | 触发条件 |
    |------------|-----------|-----------|---------|
    | `CONFIG_ERROR` | 2 | 否 | 未配置 LLM 提供商 |
    | `LLM_PROVIDER_ERROR` | 1 | 是 | LLM 提供商调用失败 |
    | `PROMPT_ERROR` | 1 | 否 | 提示词模板错误 |
  

## 两级发现

CLI 通过两个层级提供自描述的发现载荷，其设计目的是让代理无需任何预先知识即可规划出一个工作流。

### 第一级：概览

在管道中不带任何参数运行 `anysite`，即可获得一份精简的发现载荷：

```bash
anysite | jq '.result'
```

`result` 包含：

| 字段 | 描述 |
|-------|--------------|
| `status` | 当前认证方式、LLM 提供商、已保存的数据库连接、模式/关系图缓存状态 |
| `agent_protocol` | 自动 JSON、`--json`、`--human`、`--non-interactive` 的工作方式 |
| `output_schema` | 成功与失败信封结构的形状 |
| `exit_codes` | 机器可读的退出码含义 |
| `whats_new` | 最新版本的更新摘要 |
| `commands` | 每个顶层命令的描述；对于命令组，还包括每个子命令的一句话描述和一个 `detail_command` 提示 |
| `installed_extras` | 已安装的可选依赖包：`data`、`llm`、`postgres`、`clickhouse`、`mysql` |

### 第二级：分组详情

对于任意命令组，将空输入通过管道传给它即可获得完整选项、精选示例和使用提示：

```bash
echo '' | anysite db
echo '' | anysite dataset
echo '' | anysite llm
```

这会返回该分组下每个子命令的选项（提取出组内公共部分）、精选的调用示例和提示 — 例如 `db` 的提示中包括
如何将 API 输出直接通过管道传给 `db insert`。

没有子命令的顶层命令（`api`、`describe`）在管道中以空参数调用时也使用同样的机制：

```bash
echo '' | anysite api
echo '' | anysite describe
```

## 提示

返回 JSON 信封的命令还会返回**后续步骤提示** — 建议的后续命令。在 JSON 模式下它们出现在 `hints`
数组中；在人类可读模式下则以暗淡文字打印到 stderr。

```bash
anysite db add local --type sqlite --path ./data.db --json | jq -r '.hints[].command'
```

## 内置指南

数据集子系统内置了一份完整的配置参考：

```bash
# Full configuration reference
anysite dataset guide

# Specific section
anysite dataset guide --section sources

# Complete example config
anysite dataset guide --example advanced

# List all available sections and examples
anysite dataset guide --list

# JSON output for agents
anysite dataset guide --json
```

## 集成示例

### 通过管道传给 jq

```bash
anysite api /api/linkedin/user user=satyanadella | jq '.follower_count'

anysite api /api/linkedin/search/users keywords="CTO" count=10 --format jsonl | \
  jq -r '[.name, .headline] | @csv'
```

### 带错误处理的 Shell 脚本

```bash
#!/bin/bash
RESPONSE=$(anysite api /api/linkedin/user user="$1" 2>/dev/null)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "$RESPONSE" | jq '.'
elif [ $EXIT_CODE -eq 3 ]; then
  echo "Authentication failed. Check your API key."
  exit 1
elif [ $EXIT_CODE -eq 5 ]; then
  echo "Network error."
else
  echo "Error: exit code $EXIT_CODE"
  exit $EXIT_CODE
fi
```

### 代理工作流

```bash
# 1. Discover CLI capabilities and current status
anysite | jq '.result.status'

# 2. Discover available API endpoints
anysite describe --search "linkedin" --json

# 3. Inspect a specific endpoint
anysite describe /api/linkedin/user --json

# 4. Execute and check the exit code
anysite api /api/linkedin/user user=satyanadella
echo "exit: $?"
```

## 后续步骤

  
#### Dataset Pipelines

    基于同一协议构建的声明式多数据源采集
  
  
#### Installation

    安装 CLI 并配置全局选项