npm package: @huija/fx-api-cli
Description: Finex API CLI - Enterprise API command line tool for AI Agents
Latest version: 0.1.0

# fx-api-cli

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://golang.org/)

企业级 API 命令行工具 — 让人类和 AI Agent 都能在终端中操作企业系统。覆盖应用管理、数据管理、文件上传、工作流管理和企业通讯录管理等核心业务域，提供 5 大品类的 AI Agent [Skills](https://github.com/finex/fx-api-cli/tree/main/skills)。

[安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [命令](#命令参考) · [品类一览](#品类与能力一览)

## 为什么选 fx-api-cli？

- **为 AI Agent 所设计** — 开箱即用的 [Skills](https://github.com/finex/fx-api-cli/tree/main/skills)， 适配主流 AI 工具，Agent 可直接操作企业系统，无需额外适配
- **覆盖企业核心需求** — 5 大业务品类，覆盖应用管理、数据管理、文件上传、工作流管理和企业通讯录管理
- **快速上手** — `init` 配置凭证，直接调用品类工具，从安装到第一次 API 调用只需两步

## 功能

| 类别         | 能力                                                                          |
| ------------ | ----------------------------------------------------------------------------- |
| 📱 应用管理   | 应用查询、表单查询、表单字段查询                                              |
| 💾 数据管理   | 表单数据的查询、创建、更新、删除，支持批量操作                                |
| 📤 文件上传   | 文件上传凭证获取、文件上传                                                    |
| 🔄 工作流管理 | 工作流实例和任务的查询、审批、拒绝、转交、回退等操作                          |
| 👥 企业通讯录 | 用户、部门、角色和访客的查询、创建、更新和删除                                |

## 安装与快速开始

### 环境要求

- Node.js（`npm`/`npx`）
- 企业系统的 API Key

### 安装

```bash
# 安装 CLI
npm install -g @finex/fx-api-cli

# 安装 CLI SKILL（必需）
npx skills add finex/fx-api-cli -y -g
```

### 快速开始

```bash
# 1. 配置 API 凭证（交互式，仅需一次）
fx-api-cli init

# 2. 调用工具（使用短别名）
fx-api-cli app list '{"skip": 0, "limit": 10}'
```

## Agent Skills

| Skill | 品类 | 说明 |
| ----- | ---- | ---- |
| `fxapi-app-management` | 应用管理 | 应用查询、表单查询、表单字段查询 |
| `fxapi-data-management` | 数据管理 | 表单数据的查询、创建、更新、删除 |
| `fxapi-file-upload` | 文件上传 | 文件上传凭证获取、文件上传 |
| `fxapi-workflow-management` | 工作流管理 | 工作流实例和任务的查询、操作 |
| `fxapi-corp-management` | 企业通讯录 | 用户、部门、角色和访客管理 |

## 命令参考

### `--help`

列出所有支持的命令和品类。

```bash
fx-api-cli --help
```

输出示例：

```
Usage: fx-api-cli [command]

Available Commands:
  app          App management
  corp         Corporate directory
  data         Data management
  file         File upload
  workflow     Workflow management
  help         Help about any command
  init         初始化配置

Flags:
  -h, --help   help for fx-api-cli
```

### `init`

交互式配置 API 凭证，存储到本地。仅需执行一次。

```bash
fx-api-cli init
```

凭证存储位置：`~/.config/fx-api-cli/mcp-config.json`

### 品类调用

每个品类作为独立子命令使用，支持**短别名**方式。不传方法名时列出该品类下所有可用工具，传方法名时调用指定工具。

| 品类 | 短别名 |
|------|--------|
| 应用管理 | app |
| 数据管理 | data |
| 文件上传 | file |
| 工作流管理 | workflow |
| 企业通讯录 | corp |

```bash
# 列出品类下的所有工具
fx-api-cli <category>

# 调用品类下的指定工具
fx-api-cli <category> <method> [json_args]
```

示例：

```bash
# 列出应用管理品类下的工具
fx-api-cli app

# 调用工具
fx-api-cli app list '{"skip": 0, "limit": 10}'
```

## 品类与能力一览

### app — 应用管理

| 工具 | 说明 |
|------|------|
| `list` | 获取应用列表，支持分页查询 |
| `entry_list` | 获取应用下的表单列表 |
| `widget_list` | 获取表单的字段信息 |

```bash
# 获取应用列表
fx-api-cli app list '{"skip": 0, "limit": 10}'

# 获取表单列表
fx-api-cli app entry_list '{"app_id": "app_id_1"}'

# 获取表单字段
fx-api-cli app widget_list '{"app_id": "app_id_1", "entry_id": "entry_id_1"}'
```

### data — 数据管理

| 工具 | 说明 |
|------|------|
| `get` | 查询单条数据 |
| `list` | 查询多条数据，支持分页和条件过滤 |
| `create` | 新建单条数据 |
| `batch_create` | 批量新建数据 |
| `update` | 更新单条数据 |
| `batch_update` | 批量更新数据 |
| `delete` | 删除单条数据 |
| `batch_delete` | 批量删除数据 |
| `batch_hard_delete` | 批量硬删除数据 |

```bash
# 查询数据列表
fx-api-cli data list '{"app_id": "app_id_1", "entry_id": "entry_id_1", "limit": 100}'

# 创建数据
fx-api-cli data create '{"app_id": "app_id_1", "entry_id": "entry_id_1", "data": {"field1": {"value": "value1"}}}'

# 更新数据
fx-api-cli data update '{"app_id": "app_id_1", "entry_id": "entry_id_1", "data_id": "data_id_1", "data": {"field1": {"value": "updated_value"}}}'

# 删除数据
fx-api-cli data delete '{"app_id": "app_id_1", "entry_id": "entry_id_1", "data_id": "data_id_1"}'
```

### file — 文件上传

| 工具 | 说明 |
|------|------|
| `get_upload_token` | 获取文件上传凭证和上传地址 |
| `upload` | 上传文件到指定地址 |

```bash
# 获取上传凭证
fx-api-cli file get_upload_token '{"app_id": "app_id_1", "entry_id": "entry_id_1", "transaction_id": "transaction_id_1"}'

# 上传文件
fx-api-cli file upload '{"url": "upload_url", "token": "upload_token", "file": "/path/to/file"}'
```

### workflow — 工作流管理

| 工具 | 说明 |
|------|------|
| `instance_comment_list` | 获取工作流实例的评论列表 |
| `instance_get` | 获取工作流实例的详细信息 |
| `instance_log_list` | 获取工作流实例的日志列表 |
| `instance_close` | 关闭工作流实例 |
| `instance_activate` | 激活工作流实例 |
| `task_list` | 获取工作流任务列表 |
| `task_approve` | 审批工作流任务 |
| `task_rollback` | 回退工作流任务 |
| `task_transfer` | 转交工作流任务 |
| `task_add_sign` | 为工作流任务添加加签人 |
| `task_revoke` | 撤回工作流任务 |
| `task_reject` | 拒绝工作流任务 |
| `cc_list` | 获取工作流实例的抄送列表 |

```bash
# 查询工作流任务列表
fx-api-cli workflow task_list '{"app_id": "app_id_1", "entry_id": "entry_id_1"}'

# 审批工作流任务
fx-api-cli workflow task_approve '{"task_id": "task_id_1", "remark": "批准"}'

# 拒绝工作流任务
fx-api-cli workflow task_reject '{"task_id": "task_id_1", "remark": "拒绝"}'
```

### corp — 企业通讯录

| 工具 | 说明 |
|------|------|
| `user_get` | 获取用户信息 |
| `user_create` | 创建用户 |
| `user_update` | 更新用户信息 |
| `user_delete` | 删除用户 |
| `user_batch_delete` | 批量删除用户 |
| `user_import` | 导入用户 |
| `depart_user_list` | 获取部门用户列表 |
| `depart_list` | 获取部门列表 |
| `depart_create` | 创建部门 |
| `depart_update` | 更新部门信息 |
| `depart_delete` | 删除部门 |
| `depart_get` | 获取部门信息 |
| `depart_import` | 导入部门 |
| `role_list` | 获取角色列表 |
| `role_create` | 创建角色 |
| `role_update` | 更新角色信息 |
| `role_delete` | 删除角色 |
| `role_user_list` | 获取角色用户列表 |
| `role_user_add` | 向角色添加用户 |
| `role_user_remove` | 从角色中移除用户 |
| `role_group_list` | 获取角色组列表 |
| `role_group_create` | 创建角色组 |
| `role_group_update` | 更新角色组信息 |
| `role_group_delete` | 删除角色组 |
| `guest_depart_list` | 获取访客部门列表 |
| `guest_user_list` | 获取访客用户列表 |
| `guest_user_get` | 获取访客用户信息 |

```bash
# 获取部门列表
fx-api-cli corp depart_list '{}'

# 获取用户信息
fx-api-cli corp user_get '{"user_id": "user_id_1"}'

# 创建用户
fx-api-cli corp user_create '{"name": "张三", "username": "zhangsan", "departments": [1]}'
```

## 开发

本项目使用 Go 编写。

### 本地构建

```bash
# 构建当前平台
make build

# 运行测试
make test

# 代码格式化
make fmt
```

### 发布构建

```bash
# 构建所有平台到 packages 目录
make build-packages

# 查看所有可用目标
make help
```

## 许可证

本项目基于 **MIT 许可证** 开源。