# 数据连接

为智能体接入数据源：浏览「推荐数据」市场并一键启用内置数据源、完成授权（OAuth 授权与 API 密钥两种方式）、添加您机构自己的外部服务（MCP 协议或 HTTP API 两种方式），以及服务的启用、编辑、管理工具和删除。

这是配置项最多的一部分，关键概念配有白话解释，请按需查阅。

## 什么是数据连接

**白话解释：** 数据连接就是让智能体能替您查询外部金融数据的"数据源接口"。智能体本身只会"思考"，要查行情、公告、研报，必须先接上对应的数据源——就像给一位分析师配上行情终端和数据库账号，它才能真正开始干活。

每个数据源在本产品中称为一个**服务**，每个服务下包含若干**工具**——工具就是这个数据源能干的一件件具体的事（例如"查询股票行情""获取公司公告列表"）。智能体回答问题时，会自动挑选合适的工具去取数，取数过程会以"工具调用"步骤条的形式显示在对话中（详见[快速上手](/docs/workbench/quick-start.md)）。

**进入方式：** 点击左侧边栏底部您的头像 →「设置」→「当前智能体」分组 →「数据连接」。页面顶部标语为「FinX CLI」「通过 FinX CLI 连接数据与工具，帮助你将传统服务 CLI 化」，右上角有「终端测试」和「添加服务」两个按钮。

**这句标语翻译成白话是：** 平台已经把各类数据服务统一整理成标准化、随取随用的形式。您不需要理解「CLI」这类技术词，也不需要自己写任何命令——只需要开关服务和完成授权，智能体就能替您取数。

页面分为两个标签页：

- **「推荐数据」**：平台预置的数据源市场，开箱即用（见[「推荐数据」](#recommended-data)）；
- **「我的数据」**：您已接入的服务列表（含从推荐数据启用的和自行添加的）。

> **提醒：** 数据连接是"每位专家各配各的"。您在这里做的配置只对当前专家生效，切换专家后需要分别配置。

## 「推荐数据」：浏览数据市场，一键启用内置数据源

「推荐数据」标签页是平台已经接好的数据源市场，您不需要懂任何技术，找到想用的打开开关即可。

1. 在「数据连接」页面点击「推荐数据」标签页。
2. 数据源按供应商分组展示，每组标题形如「供应商名 · N 个服务」，右侧显示该组的启用进度（如「2/5 已启用」）和待授权数量（如「1 待授权」）；不属于特定供应商的归入「综合服务」分区。
3. 可以用顶部搜索框（提示文字「搜索推荐数据…」）按名称查找，或点击分类标签（「全部」及各业务分类）过滤，列表上方显示「共 N 个服务」。

![推荐数据市场](/docs/images/workbench/04-market-01.png)

每张服务卡片上包含：

- **名称与简介**：这个数据源是什么、提供哪些数据；
- **类型标签**：「MCP」或「HTTP」（技术接入方式，日常使用无需关心，含义见[添加自定义外部服务](#add-external-service)）；
- **「N 个工具」**：点击可预览该服务的全部工具清单（见[预览工具列表](#preview-tools)）；
- **授权状态**：「内置授权」（平台已代为配置，无需操作）、「已授权」「未授权」或「授权」按钮（见[授权](#authorization)）；
- **右上角开关**：启用 / 停用该服务。

**一键启用：** 对于标有「内置授权」的服务，直接点开卡片右上角的开关即可，智能体立刻就能使用。需要授权的服务请先完成授权（开关上会提示「请先完成授权后再启用」，直接点击会提示「该工具需先完成授权才能启用」并自动弹出授权窗口）。

> **如果您没有看到某个数据源**：推荐数据的内容由平台和您所在机构配置，不同机构可见范围不同，属于正常情况。

## 授权：让数据源认识您

### 什么是授权，如何识别授权状态

**白话解释：** 有些数据源属于第三方服务，按账号计费或需要验证使用者身份，因此在使用前需要"报上您的身份"——这个过程就叫授权。就像开通银行的一项新业务前需要先签约，授权通常只需操作一次。

在服务卡片上可以看到授权状态：

| 卡片上的显示 | 含义 |
| --- | --- |
| 「内置授权」 | 平台已统一配置好，您无需做任何事 |
| 「已授权」 | 您已完成授权，可正常启用使用 |
| 「未授权」 | 尚未授权，需要先完成授权才能启用 |
| 「授权」按钮 | 点击即可开始授权流程 |
| 「授权中…」 | 授权正在进行，请稍候 |

授权分为两种方式，界面会根据服务自动展示对应的一种，您不需要自己选择——但了解"什么情况是哪种"有助于您准备好所需材料：

- **OAuth 授权**（详见下文「OAuth 授权」小节）：**适用场景**——数据提供方支持"跳转登录确认"的授权模式。特征是不需要您填写任何内容：点击授权后，可能弹出仅含「去授权」按钮的窗口，也可能直接跳转到服务提供商的授权页面。适合您在数据提供方已有账号的情况，全程点几下鼠标即可。
- **API 密钥等表单授权**（详见下文「API 密钥等表单授权」小节）：**适用场景**——数据提供方以"密钥"（一串字符）作为身份凭证。特征是弹窗里有需要填写的输入框。您需要事先从数据服务商处获取密钥。

### OAuth 授权：跳转到数据提供方页面确认

**白话解释：** OAuth 授权的过程是——系统把您带到**数据提供方自己的页面**，您在那里登录并点击"同意"，等于当面告诉数据提供方："我允许点金 FinX 代我来取数。"您的账号密码只输入在数据提供方的页面上，本产品不会看到，安全性有保障。

操作步骤：

1. 在服务卡片上点击「授权」按钮。

![推荐数据服务卡片上的「授权」按钮（左侧卡片右下角）](/docs/images/workbench/04-oauth-01.png)

1. 接下来视服务配置而定，可能出现两种情形之一：
  - 弹出「授权设置」窗口，提示「该服务需要 OAuth 授权，请点击下方按钮前往服务提供商完成授权。」点击「去授权」后，浏览器打开新窗口进入授权页面；
  - 也可能不经弹窗，直接在新窗口打开服务提供商的授权页面。
2. 在新窗口按数据提供方页面的提示登录并同意授权。期间原页面可能显示「等待授权中…」和「已在新窗口打开授权页面，完成授权后将自动更新状态」。
3. 完成确认后回到本产品，系统会自动检测授权结果并提示「授权成功」，卡片状态变为「已授权」。

> - **等了很久没有反应**：系统最长等待约 5 分钟，超时会提示「授权超时，请重新尝试」，重新点「去授权」再来一次即可。
> - **新窗口没有弹出来**：可能被浏览器拦截了，请允许本网站弹出窗口后重试。
> - **想收回授权**：再次打开「授权设置」窗口，已授权状态下会显示「已授权」和「授权时间」，点击「撤销授权」并确认（提示「确定要撤销该服务的 OAuth 授权吗？」）即可，之后提示「已撤销授权」。撤销后该服务将无法取数，直到重新授权。

### API 密钥（API Key）等表单授权

**白话解释：** API 密钥（也叫 API Key）是数据服务商发给您的一串字符，相当于一把专属钥匙——出示这把钥匙，服务商就知道是您在取数。**密钥去哪里获取？** 由数据服务商提供：通常在您与服务商开通数据服务后，登录服务商的官网或管理后台可以查到，也可能由服务商的对接人员直接发给您。如果不清楚，请联系该数据服务的销售或客服，或咨询您机构的管理员。

操作步骤：

1. 在服务卡片上点击「授权」，弹出「授权设置」窗口。这类服务的窗口中会显示需要填写的字段（带「必填」「选填」标记），部分服务还会在窗口中给出凭证获取指引（含跳转到服务商页面的链接按钮）。
2. 把从服务商处获取的密钥粘贴到对应输入框。若之前配置过，字段会显示「当前值: ×××（留空保留原值）」（界面原文如此，此处为半角冒号），不修改的字段留空即可；已配置完整的服务会标有「已配置」。
3. 点击「保存」。系统依次执行「正在提交凭证…」→「后端验证授权有效性…」两步——即保存后立刻拿您的密钥去服务商那里"试一下门"，确认真的能打开。
4. 验证通过显示「授权验证通过」，窗口自动关闭，卡片状态变为「已授权」。

> - **提示「授权验证失败」或「凭证校验未通过，请检查后重试」**：多为密钥抄错（多空格、少字符）或密钥已过期。点「返回修改」重新粘贴，或向服务商确认密钥状态后点「重新提交」。
> - **提示「请填写：×××」**：还有必填字段没填。
> - 使用中如遇"之前能查、现在突然查不了"，常见原因是授权过期，重新授权一次即可。更多失败情形见 [常见问题](/docs/workbench/faq.md)。

## 添加自定义外部服务

除了推荐数据，您还可以把机构自己的数据服务接入进来。点击「数据连接」页面右上角的「添加服务」，弹出「添加外部服务」窗口（副标题「选择服务类型开始配置」），提供两种方式：

> **谁来完成本节配置：** 本节的配置工作主要由您机构的技术同事或数据服务商完成，涉及的配置信息（配置文本、服务地址、认证凭证等）均应来自他们。作为业务用户，您只需要知道：**「MCP 协议」方式 ≈ 把服务商给您的一段配置粘贴进来；「HTTP API」方式 ≈ 技术同事照着接口文档逐项配置。** 遇到不理解的字段，直接转交技术同事即可——配置错误会导致连接失败。

![添加外部服务窗口](/docs/images/workbench/04-add-service-01.png)

| 方式 | 界面说明 | 什么情况选它 |
| --- | --- | --- |
| 「MCP 协议」 | 粘贴 MCP Server URL，系统自动连接并发现所有可用工具，AI 自动生成工具描述。（标签：自动发现 / AI 描述 / 零配置） | 服务商明确告诉您"我们支持 MCP"并给了您一段 JSON 配置或一个 MCP 地址。**推荐优先选这种**——粘贴即用，工具清单自动生成，几乎不需要配置。 |
| 「HTTP API」 | 填写 Base URL 和认证方式，然后手动定义每个工具端点的参数 Schema。（标签：REST API / 自定义 Schema / 灵活配置） | 服务商只提供普通的 HTTP 接口（接口文档形式）。需要逐个手工定义工具，通常由您机构的技术同事协助完成。 |

**白话解释——什么是 MCP：** MCP 是一种让智能体连接外部数据的**通用接口标准**，可以理解为数据服务领域的"标准插头"：只要服务商按这个标准提供服务，粘贴一段配置就能接上，系统会自动"发现"它有哪些工具，无需逐个手工登记。

**白话解释——什么是 HTTP API：** 就是传统的网络接口，没有统一插头，需要照着服务商的接口文档手工"接线"（逐个填写每个工具的地址和参数）。

### MCP 协议方式

选择「MCP 协议」后进入「添加 MCP 服务」（副标题「选择添加方式」），有两种添加方式：

- **「JSON 导入」**——粘贴 MCP Server 的 JSON 配置，快速导入服务定义（标签：快速导入 / 批量配置）。**适合**：服务商直接给了您一段 JSON 配置文本，这是最快的方式，支持一次导入多个服务。
- **「直接配置」**——填写 MCP Server URL 和认证信息，系统自动连接并发现工具（标签：自动发现 / AI 描述 / 精细配置）。**适合**：服务商只给了地址和凭证，或需要更精细地调整配置。

**JSON 导入步骤：**

1. 选择「JSON 导入」，页面说明为「粘贴符合 MCP 配置规范的 JSON，支持 streamable-http 和 sse 两种传输协议，可通过 headers 字段配置授权信息。」（页面还提供「示例：streamable-http」「示例：sse」两个示例按钮，分别对应两种传输方式的配置格式，可参考——传输方式选哪种由服务商决定，照着粘贴即可）。
2. 把服务商提供的配置文本原样粘贴到输入框，点击「导入配置」。
3. 界面显示「正在导入...」「正在将 MCP 服务配置导入到智能体」及进度。完成后提示「已添加「服务名」」（一次导入多个时提示「已导入 N 个 MCP 服务」），新服务出现在「我的数据」中。

> - **提示「JSON 格式无效，请检查后重试」**：粘贴的内容不是完整的 JSON，请检查是否漏复制了开头或结尾。
> - **提示「未找到有效的 MCP Server 配置」或「以下服务缺少 url 字段」**：配置内容不符合规范，请向服务商索要正确的配置。

**直接配置步骤：** 选择「直接配置」进入「创建 MCP 服务」页面，填写「服务标识」（英文标识符）、「显示名称」（中文展示名，选填）、「服务地址」和「认证方式」等信息后提交。系统会依次执行「正在检查服务配置」→「正在连接 MCP 服务」→「正在生成服务名称」→「正在生成服务描述」→「正在保存服务」，最后显示「服务创建完成」——也就是说连服务的名称、描述都由 AI 自动生成，无需手写。

> 创建失败时的常见提示：「无法连接到 MCP 服务。请确认 Server URL 正确、服务已启动，并且当前网络可以访问。」「连接 MCP 服务超时。请检查服务状态或适当延长超时时间后重试。」「MCP 服务拒绝了本次访问。请检查认证方式和凭证是否正确。」——分别对应地址错误、网络问题和凭证问题，请对照检查或联系服务商。

### HTTP API 方式

选择「HTTP API」进入「创建 HTTP 服务」页面（此方式配置项较多，建议由技术同事协助）：

1. **基本信息**：填写「服务标识」（提示「如 stock_query（英文标识符，字母/数字/下划线/连字符）」）、「显示名称」（提示「中文展示名（选填）」）、「服务描述」（可点「AI 自动生成」）。
2. **「基础地址」**：服务商接口的根地址（必填）。
3. **「认证方式」**：下拉选择「无需认证」「API 密钥」「Bearer 令牌」「Basic 认证（用户名密码）」「自定义 Header」「动态 Token（OAuth 等）」之一，并按提示填写对应凭证（如「密钥值」「Header 名称」等）。选哪种由服务商的接口文档决定。
4. 点击「创建服务」，成功后提示「HTTP 服务创建成功」。

刚创建的 HTTP 服务还没有工具，需要继续为它添加工具端点，见[管理工具](#manage-tools)。

**白话解释——「动态 Token（OAuth 等）」怎么配：** 当服务商要求"先用一组凭证换一个短期有效的 Token，再用这个 Token 去调接口"时，选这种认证。您需要填：Token 换取地址、请求方法、Token 字段名、请求头 KV、请求体、过期字段、注入 Header、Token 前缀。全部参数由服务商提供，粘贴即可。

## 运行时变量占位符（动态 Token / 自定义 Header 场景）

**白话解释：** 占位符是写在配置里、调用时才被真实值替换的"模板槽"。例如把 `${sys.principalId}` 填在请求头里，系统每次调用时会自动换成当前使用者的身份 ID——不用您为每位用户维护一份独立配置。

**支持占位符的字段**（填写时右侧会显示绿色「支持运行时变量」提示 + Tooltip 列出可用变量）：

- 「API 密钥」的密钥值
- 「Bearer 令牌」的 Token 值
- 「自定义 Header」的 Header 值
- 「动态 Token（OAuth 等）」的：Token 换取 URL、请求头的 Value、请求体整个 JSON

**不支持占位符的字段**（填写时会显示红色「不支持运行时变量」/「服务地址不支持运行时变量」）：

- HTTP 服务的「基础地址」/ Base URL
- MCP 服务的「服务地址」

### 可用的占位符

| 占位符 | 替换内容 |
| --- | --- |
| `${sys.principalId}` | 当前使用者的身份主体 ID |
| `${sys.sessionId}` | 当前会话 ID |
| `${sys.agentId}` | 当前使用的智能体 ID |
| `${sys.requestId}` | 当前请求 ID（可追踪一次调用） |
| `${ctx.自定义名}` | 由用户 / 智能体传入的运行时上下文字段，名字自定（如 `${ctx.departmentCode}`） |

### MCP 服务的"测试值"收集

创建 / 保存 MCP 服务时，如果您在配置里用了 `${ctx.自定义名}` 这类上下文占位符，系统会弹出「测试变量」窗口让您填一组测试值，用来真正跑一次连通性校验，防止配好后到运行时才发现填错。

## 启用 / 停用服务，编辑服务

**启用 / 停用**：无论在「推荐数据」还是「我的数据」，每张服务卡片右上角都有开关。打开后智能体才能使用该服务的工具；停用后智能体将不再查询它（已有的配置和授权保留，随时可重新打开）。需要授权的服务必须先完成授权才能启用（开关会提示「请先完成授权后再启用」）。

**白话解释——开关对对话的影响：** 打开的服务越多，智能体可选的取数渠道越多，但同类数据源开太多也可能让它"挑花眼"。建议只打开您实际需要的数据源。

**编辑服务**（仅自行添加的服务）：在「我的数据」中点击服务卡片右下角的三点菜单（「更多操作」），选择「编辑服务」，进入「编辑 MCP 服务」或「编辑 HTTP 服务」页面，可修改地址、认证方式等配置，改完点「保存修改」（提示「HTTP 服务已更新」等）。

![「我的数据」中自建服务卡片的三点菜单：编辑服务 / 管理工具 / 删除服务](/docs/images/workbench/04-my-services-01.png)

> 平台内置服务不提供编辑、删除等操作，卡片上不会出现三点菜单，属于正常情况。

## 管理工具：HTTP 服务的工具端点增删改

HTTP 类型的服务需要手工维护"工具清单"。在服务卡片的三点菜单中选择「管理工具」（仅 HTTP 服务有此选项），进入工具管理页面：

- **添加**：点击「添加工具」（服务还没有工具时显示「为此 HTTP 服务添加工具端点」和「添加第一个工具」）。在「添加工具」窗口中填写：
  - 「工具名称」（提示「如：get_stock_price」，要求「字母/数字/下划线，同服务内唯一」）；
  - 「描述」（提示「描述此工具的功能」——请认真填写，智能体靠这段描述判断什么时候使用该工具）；
  - 「接口路径」（提示「/api/stock/query（相对于基础地址）」，「支持 {xxx} 路径变量，会自动从参数中提取填充」）；
  - 「参数定义」（粘贴 JSON Schema，「使用 JSON Schema 格式定义工具的全部参数结构」）；
  - 「超时时间（ms）」（选填，「留空为默认」）。 完成后点「添加工具」，提示「工具已添加」。
- **修改**：点击工具行的「编辑工具」，窗口标题为「编辑工具」（副标题「修改「工具名」的配置」），改完点「保存修改」，提示「工具已更新」。
- **删除**：点击工具行的「删除工具」，确认框提示「确认删除工具「工具名」？此操作不可撤销。」点「确认删除」，提示「已删除「工具名」」。

> 「参数定义」使用的是一种技术配置格式（即输入框提示中提到的 JSON Schema），内容应来自服务商的接口文档，建议由技术同事填写。

## 预览工具列表

想知道某个服务到底能干什么，点击服务卡片上的「N 个工具」标签，弹出「工具预览 · 服务名」窗口（副标题显示「共 N 个工具」），逐个列出该服务的工具及其参数（「参数名」「类型」「必填」「描述」）。这里只能查看，不能修改；MCP 服务的工具清单由系统自动发现，无需人工维护。

> 若显示「该服务暂无可用工具」，MCP 服务请检查连接状态（卡片上的「已连接」「连接中」「连接失败」「未连接」），HTTP 服务请先按[管理工具](#manage-tools)添加工具。

## 删除服务

仅自行添加的服务可删除：

1. 在「我的数据」中点击服务卡片的三点菜单，选择「删除服务」。
2. 弹出「删除服务」确认框：「确认删除「服务名」？删除后，该服务及其所有工具将不可用。此操作不可撤销。」
3. 点击「确认删除」，完成后提示「已删除「服务名」」。

如果只是暂时不用，建议用开关停用而不是删除——删除后所有配置需要重新录入。

## FinX 终端测试（了解即可）

「数据连接」页面右上角的「终端测试」按钮会打开「FinX 测试终端」窗口（副标题「直接调用 FinX 命令，用于调试和验证」），供技术人员在不发起对话的情况下直接调用服务命令、验证配置是否生效。日常使用不需要打开它；如果服务表现异常，可以请技术同事借助此工具排查。

## 常见问题速查

| 现象 | 可能原因与处理 |
| --- | --- |
| 开关打不开，提示「请先完成授权后再启用」 | 该服务需要授权，按[授权](#authorization)完成授权后再启用 |
| 之前能查，现在查不了 | 常见为授权过期，重新走一遍授权流程即可 |
| MCP 服务卡片显示「连接失败」 | 服务地址、凭证或网络问题，参考「MCP 协议方式」小节的失败提示对照检查 |
| 「授权验证失败」 | 密钥抄错或已失效，重新粘贴或联系服务商 |

更多问题与报错处理详见 [常见问题](/docs/workbench/faq.md)。

## 下一步

- 让智能体参考您自己的文档资料：[知识管理](/docs/workbench/knowledge.md)
- 回顾对话中数据源授权弹窗的处理：[对话与会话](/docs/workbench/chat-and-sessions.md)
- 管理专家团队：[智能体管理](/docs/workbench/experts.md)