代理协议

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

概述

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

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

# 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。运行 anysite <command> --help 可以检查某个命令是否有 --json 标志。

JSON 信封

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

成功：

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

失败：

{
  "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 给出后续命令建议：

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	网络错误	连接失败、超时、速率限制

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，即可获得一份精简的发现载荷：

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

第二级：分组详情

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

echo '' | anysite db
echo '' | anysite dataset
echo '' | anysite llm

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

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

echo '' | anysite api
echo '' | anysite describe

提示

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

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

内置指南

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

# 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

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 脚本

#!/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

代理工作流

# 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 并配置全局选项