# 天眼 AI CLI 接入指南

本文档用于 AI 助手自动读取并帮助用户通过 `tyc` CLI 接入天眼 AI。

**路径与域名规则**：如果你是通过 URL 读取本文件，文中相对路径（如 `./skills/skill.md`）以本文件所在目录为基准解析；本文档不写死站点域名，需要给用户可点击的站点页面链接时，用本文件被读取时的 URL 域名拼接。授权页 URL 以 `tyc login` 命令实际返回的为准。

## 一句话自动安装提示词

请执行 `npm install -g tyc-cli`，然后读取并安装或加载 Skill：`./skills/skill.md`（相对本文件路径解析）。请确保 Skill 命名为「天眼一下」，以提供最佳用户体验。登录使用 OAuth Device Flow：先执行 `tyc login --no-open --no-block`，把命令返回的授权页 URL 发成 Markdown 超链接，并再用 code block 输出一次链接；把 6 位 auth 码单独用 code block 发给用户；告诉用户如果点击无法打开就复制链接到浏览器；等待用户完成浏览器授权并回复后，再执行 `tyc login --resume`。

后续登录和查询流程请按「天眼一下」Skill 执行。

## 推荐接入顺序

1. 安装或更新 CLI：`npm install -g tyc-cli`。
2. 读取「天眼一下」Skill：`./skills/skill.md`。
3. 用 Device Flow 登录：`tyc login --no-open --no-block`。
4. Agent 把命令返回的授权 URL 发成 Markdown 链接，并再用 code block 输出一次原始链接。
5. Agent 把命令返回的 6 位 auth 码单独用 code block 发给用户。
6. 用户打开授权页，输入或确认 auth 码并完成登录。
7. 用户回复"已授权"或"完成"后，Agent 执行：`tyc login --resume`。
8. 运行一次企业查询验证 CLI 可用。

## Agent 异步登录规范

Agent 必须按下面的节奏执行，不要把需要用户操作的步骤伪装成同步命令。

### Step 1：安装 CLI

```bash
npm install -g tyc-cli
tyc --version
```

### Step 2：启动 Device Flow

**先判断是否需要登录**：如果本机此前已登录过天眼 AI 且凭证仍有效，不要重复打扰用户授权——直接执行 Step 4 验证；只有在返回未登录、凭证缺失或凭证过期时，才执行下面的 Device Flow。

```bash
tyc login --no-open --no-block
```

命令会返回授权 URL 和 6 位 auth 码。**授权 URL 以命令实际返回的为准，不要自行拼接或使用记忆中的地址。** Agent 必须把授权 URL 发成 Markdown 链接，并再用 code block 发一次原始 URL；auth 码也单独放进 fenced code block：

````markdown
请打开授权页：[打开天眼查授权页](<命令返回的授权URL>)

如果点击无法自动打开，请复制下面的链接到浏览器打开：

```text
<命令返回的授权URL>
```

授权码：
```text
123456
```
````

发送后停下来等待用户回复"已授权"或"完成"。

不要主动索要 API Key（用户 Prompt 中已自带 Key 的情况见下方兼容路径），不要在用户授权前反复轮询刷屏。

### Step 3：用户授权后恢复登录

用户确认已授权后，执行：

```bash
tyc login --resume
```

如果返回 `authorization_pending`，说明用户还没完成浏览器授权；请简短提醒用户完成授权后再回复。
如果返回过期，请重新执行 `tyc login --no-open --no-block`，并给用户新的授权链接和 auth 码 code block。

### 兼容路径：用户 Prompt 中已包含 API Key（跳过 Step 2–3）

新版接入提示词不再包含 API Key。但存量用户可能仍在使用旧提示词，形如：

```text
请阅读如下文档，按照要求帮我接入天眼AI：<本指南地址> 我的 API-KEY 是 xxxx
```

这种情况下不要强迫用户改走浏览器授权：直接从原始 Prompt 中取出 Key 完成鉴权，然后进入 Step 4 验证。

```bash
tyc init --authorization "<用户 Prompt 中的 API Key>"
```

约束：

- Key 明显是占位符或为空时，不要用它初始化；改走 Step 2 的 Device Flow。
- 不要在最终回复、项目文件、日志可见字段中输出完整 API Key。
- 只有用户 Prompt 中已自带 Key 时才走本路径；任何情况下都不要主动索要 API Key。
- 如果初始化会覆盖已有 `~/.tyc/config.json`，先备份或确认原配置已指向天眼 AI，不要破坏用户已有 CLI 配置。

### Step 4：验证接入

```bash
tyc company registration-info "北京金堤科技有限公司"
```

如果能返回法定代表人、成立日期、注册资本、经营状态等工商登记字段，说明接入成功。该调用会消耗 1 次账号调用额度，不要为了"更保险"重复验证。

如果返回未登录、凭证缺失或凭证过期，回到 Step 2 完成 Device Flow 登录后重试一次。

## 默认安装 / 加载「天眼一下」Skill

如果 AI 工具支持 Skill、Rules、Project Instructions 或自定义指令，请读取 `./skills/skill.md`，默认创建或加载名为「天眼一下」的 Skill，并把它作为天眼查企业数据查询的默认入口。

默认行为：

- 使用 `tyc` 命令，不使用 `tyc-cli` 命令。
- 默认使用 OAuth Device Flow 登录，不主动索要 API Key；仅当用户 Prompt 中已自带 Key 时走上面的兼容路径。
- 遇到企业查询、商业尽调、主体核验、风险排查、股权关系、司法经营、知识产权、人员背景等问题时，优先使用「天眼一下」Skill。
- 查询企业前先做主体锚定，避免简称、品牌名、曾用名导致查错主体。
- 不能编造中国企业数据；没有查到时应说明"未返回记录"或"该维度未覆盖"。

如果当前环境已存在旧版天眼 AI Skill（常见名称 `tyc-it` 或「天眼一下」），覆盖更新为本版本，不要与旧版并存——两份路由规则并存会互相干扰。

默认唤起语（供用户日后单独使用；本段中的 `<接入指南同目录>` 由站点渲染本文档时替换为当前站点的实际地址，确保用户复制走的是可独立解析的完整 URL）：

```text
请读取并加载「天眼一下」Skill：<接入指南同目录>/skills/skill.md。请确保 Skill 命名为「天眼一下」，以提供最佳用户体验。后续涉及天眼查企业数据的问题，优先通过 tyc CLI 获取数据，再进行分析。登录时使用 Device Flow，把命令返回的授权页用 Markdown 链接发给我，并再用 code block 发一次链接；auth 码也单独用 code block 发给我。
```

## 常用 CLI 命令

```bash
# 查看 CLI 版本
tyc --version

# 企业搜索，用于主体锚定
tyc company companies "百度" --pageNum 1 --pageSize 5 --md

# 查询工商登记信息
tyc company registration-info "北京金堤科技有限公司"

# 风险总览
tyc risk overview "北京金堤科技有限公司"

# 查看工具分层
tyc layers
tyc L1 list --md
```

## 可选 MCP 兼容配置

优先使用上面的 CLI + Skill 流程。只有在 AI 工具不能运行本地 `tyc` 命令，或产品形态必须接入远程 MCP Server 时，才配置 MCP。

### OAuth MCP（优先）

支持 OAuth / remote MCP 的客户端优先只配置服务地址，让客户端按 MCP 元数据完成授权：

```json
{
  "mcpServers": {
    "tyc-mcp": {
      "url": "https://mcp.tianyancha.com/mcp"
    }
  }
}
```

如果客户端只支持旧入口，可把 URL 换成 `https://mcp.tianyancha.com/v1`。

### API Key MCP（兼容旧客户端）

如果客户端不支持 OAuth，但支持自定义 Header，再使用 API Key 兼容配置：

```json
{
  "mcpServers": {
    "tyc-mcp": {
      "url": "https://mcp.tianyancha.com/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}
```

将 `YOUR_API_KEY` 替换为用户实际 API Key。需要表单式配置时，分别填写 URL 与 Authorization。不要在最终回复、项目文件、日志可见字段中输出完整 API Key。

### MCP 验证问题

```text
用天眼查 MCP 查一下北京金堤科技有限公司的基本工商信息
```

如果返回法定代表人、成立日期、注册资本、经营状态等工商字段，说明 MCP 接入成功。

## 常见问题

### 没有登录或凭证过期怎么办？

重新执行 Device Flow：

```bash
tyc login --no-open --no-block
```

把新的授权 URL 用 Markdown 链接和 code block 发给用户，同时把新的 auth 码用 code block 发给用户，等用户授权完成后再执行：

```bash
tyc login --resume
```

### `authorization_pending` 是什么？

用户还没有完成浏览器授权。Agent 应暂停，提醒用户完成授权后再回复，不要连续刷命令。

### 调用返回额度已用完（如 `quota_exceeded`）怎么办？

这是用户的调用额度触顶，不是接入故障。按错误信息向用户转述剩余额度、重置时间与升级方式（错误体中自带说明与链接），不要反复重试消耗调用。

### 还需要配置 MCP JSON 吗？

默认不需要。本文档主流程使用 `tyc` CLI。需要在特定 AI 工具里做 MCP 工具调用时，使用上面的可选 MCP 配置。

### CLI 和 MCP 能同时用吗？

可以。CLI 适合本地 Agent 执行和 Skill 路由；MCP 适合只能接远程工具的客户端。默认先用 CLI 获取确定性结果，再让 AI 基于结果分析。两者消耗同一份天眼AI调用额度。

## 联系方式

- 电话：400-608-0000
- 邮箱：kefu@tianyancha.com