# 执行Finx命令

`POST` `/api/agent/finx/execute`

执行 Finx CLI 命令，用于调试服务与工具是否配置正确（包括地址、参数与鉴权凭证）。

**命令格式**：`finx <服务名> <工具名> [--参数名 参数值 ...] [--body '<请求体JSON>']`，命令必须以 `finx` 开头，不支持管道等 shell 操作符。

**不确定参数时先查 --help**：`finx --help` 列服务，`finx <服务名> --help` 列工具，`finx <服务名> <工具名> --help` 看准确入参与请求体要求。

**调用样例**：`finx example-api search-news --body '{"query":"宁德时代最新研报"}'`。

**凭证缺失时**：若该服务要求用户自备凭证且当前身份尚未配置，执行会失败，请先调用 getAuthSchema + saveAuthCredential 完成授权。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| agentId | integer | 否 | 智能体ID（可选）。传入时只能调用该智能体可用的服务，并使用该智能体下的凭证 |
| command | string | 是 | **Finx 命令，格式：`finx <服务名> <工具名> [--参数名 参数值 ...] [--body '<请求体JSON>']`**
- 参数名与该工具 parameterSchema 中声明的属性名一致；走 URL 查询参数或路径变量的用 `--参数名 值`，请求体参数统一放在 `--body` 的 JSON 里
- 命令必须以 `finx` 开头，且不支持管道等 shell 操作符
- 任意层级都可以加 `--help` 查看用法：
  - `finx --help`：列出当前可用的全部服务
  - `finx <服务名> --help`：列出该服务下的工具
  - `finx <服务名> <工具名> --help`：查看该工具的准确参数与请求体要求
- 示例：`finx eastmoney-mx search-news --body '{"query":"宁德时代最新研报","limit":10}'`
- 示例（参数走 URL）：`finx market-data quote --symbol 600519 --period 1d` |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | string | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |