fatsand/JIAP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
fatsand 2024-12-19 10:15:23 +08:00
commit c036c8c168
6 changed files with 1931 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

546
JIAP_Develop.md Normal file
View File

@ -0,0 +1,546 @@
# 九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol, JIAP) 开发文档
**JIAP** 是“九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol)”的缩写，它定义了一套统一、高效、可扩展的机器人流程自动化（RPA）框架。该协议旨在实现跨多种自动化工具和平台的无缝集成，同时确保与主流标准兼容。
## 开发文档
### 九鑫智能自动化协议 (JIAP) 开发文档
---
### 目录
1. [简介](#1-简介)
2. [系统架构](#2-系统架构)
3. [API 设计与通信标准](#3-api-设计与通信标准)
4. [模块与方法](#4-模块与方法)
5. [数据模型](#5-数据模型)
6. [认证与安全](#6-认证与安全)
7. [错误处理](#7-错误处理)
8. [可扩展性](#8-可扩展性)
9. [示例与使用场景](#9-示例与使用场景)
10. [常见问题](#10-常见问题)
---
## 1. 简介
**九鑫智能自动化协议 (JiuXin Intelligent Automation Protocol, JIAP)** 提供了一套标准化框架，用于设计、执行和管理 RPA 工作流。目标如下：
- **实现无缝集成**：支持多样化的系统。
- **简化自动化任务**：通过统一的接口执行操作。
- **确保兼容性**：与主流 RPA 平台和协议兼容。
### 核心特点：
- **模块化**：提供文件操作、数据处理、系统任务等功能模块。
- **可扩展性**：支持动态添加新模块及定制化工作流。
- **兼容性**：支持 RESTful API、WebSocket 等主流协议的集成。
- **安全性**：高级认证机制与加密数据传输。
---
## 2. 系统架构
### 核心组件
1. **RPA 控制器**：
- 负责任务调度、机器人协调及资源分配。
- 提供外部系统可调用的 API 接口。
2. **机器人代理**：
- 执行由控制器分配的自动化任务。
- 与控制器通信，报告任务状态和结果。
3. **活动模块**：
- 独立的功能单元，例如文件处理、Excel 操作、数据库访问等。
- 易于扩展，可根据需求添加新功能。
4. **日志与监控系统**：
- 记录任务执行日志。
- 提供性能分析与故障排查信息。
---
## 3. API 设计与通信标准
### 3.1 通信协议
- **RESTful API**：
- 基础 URL: `https://api.jiuxinai.com/v1/jiap`
- 用于同步任务请求与查询操作。
- **WebSocket**：
- URL: `wss://api.jiuxinai.com/ws`
- 支持异步任务执行与实时通信。
### 3.2 标准请求格式
```json
{
"method": "<模块>.<操作>",
"params": {
"param1": "value1",
"param2": "value2"
}
}
```
### 3.3 标准响应格式
```json
{
"status": "success", // success 或 error
"message": "操作描述",
"data": {
"key1": "value1",
"key2": "value2"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
## 4. 模块与方法
### 4.1 文件操作模块
| 方法名 | 描述 | 参数 |
|-------------------|----------------------|-------------------------------------|
| `File.Copy` | 复制文件 | `source_path`, `destination_path`, `overwrite` |
| `File.Delete` | 删除文件 | `file_path` |
| `File.Rename` | 重命名文件 | `file_path`, `new_name` |
| `File.ListFiles` | 列出目录中的文件 | `directory_path`, `filter_by_extension` |
---
### 4.2 Excel 操作模块
| 方法名 | 描述 | 参数 |
|-----------------------|--------------------------|---------------------------------------|
| `Excel.ReadCell` | 读取 Excel 单元格数据 | `file_path`, `sheet_name`, `cell_name`, `password` |
| `Excel.WriteCell` | 写入 Excel 单元格数据 | `file_path`, `sheet_name`, `cell_name`, `value`, `password` |
| `Excel.MergeCells` | 合并或取消合并单元格 | `file_path`, `sheet_name`, `range_name`, `action` |
---
### 4.3 网络模块
| 方法名 | 描述 | 参数 |
|-----------------------|----------------------|-----------------------------------|
| `Network.HttpGet` | 执行 HTTP GET 请求 | `url`, `headers` |
| `Network.HttpPost` | 执行 HTTP POST 请求 | `url`, `headers`, `body` |
| `Network.DownloadFile`| 下载文件 | `url`, `save_path` |
---
### 4.4 OCR 模块
| 方法名 | 描述 | 参数 |
|-----------------------|----------------------|-----------------------------------|
| `OCR.ExtractText` | 从图像中提取文本 | `image_path` |
| `OCR.ExtractFromPDF` | 从 PDF 中提取文本 | `pdf_path` |
---
### 4.5 扩展模块
其他模块（如数据库操作、系统命令）可根据需要动态添加。有关详细信息，请参考可扩展性部分。
---
## 5. 数据模型
### 文件元数据模型
```json
{
"path": "/path/to/file.txt",
"size": 1024,
"created_at": "2024-04-01T10:00:00Z",
"modified_at": "2024-04-28T10:00:00Z"
}
```
### Excel 单元格数据模型
```json
{
"file_path": "/path/to/excel.xlsx",
"sheet_name": "Sheet1",
"cell_name": "A1",
"value": "123"
}
```
---
## 6. 认证与安全
### 6.1 认证
- **OAuth 2.0**：
- 使用访问令牌进行 API 请求。
- 认证端点: `https://api.jiuxinai.com/auth/token`
- **API 密钥**：
- 简化认证流程，适用于内部场景。
### 6.2 数据安全
- 使用 HTTPS 和 WSS 进行加密通信。
- 敏感数据（如密码）采用行业标准加密存储。
---
## 7. 错误处理
标准化错误响应，确保交互可预测且易于调试。
### 示例错误响应
```json
{
"status": "error",
"message": "文件未找到",
"data": null,
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
## 8. 可扩展性
### 添加新模块
1. 在配置文件中定义模块和方法。
2. 在后端实现模块逻辑。
3. 通过控制器公开新模块。
### 自定义操作
开发者可通过配置文件或脚本添加自定义工作流，从而扩展协议的功能。
---
## 9. 示例与使用场景
### 示例：文件复制操作
**请求**：
```json
{
"method": "File.Copy",
"params": {
"source_path": "/source/file.txt",
"destination_path": "/destination/file.txt",
"overwrite": true
}
}
```
**响应**：
```json
{
"status": "success",
"message": "文件复制成功",
"data": {
"source_path": "/source/file.txt",
"destination_path": "/destination/file.txt",
"overwrite": true
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
## 10. 常见问题
1. **如何进行 API 请求认证？**
使用 OAuth 2.0 令牌或 API 密钥。
2. **JIAP 是否支持主流 RPA 平台集成？**
是的，JIAP 通过 RESTful API 实现了与主流 RPA 工具的兼容。
---
以上文档为实现和集成 **九鑫智能自动化协议 (JIAP)** 提供了全面指导。如需更多信息，请联系 **九鑫智能技术支持**：[xiaoyigong@9xin.ai]。
## 协议英文名称
**JiuXin Intelligent Automation Protocol (JIAP)**
**JIAP** stands for "JiuXin Intelligent Automation Protocol," which defines a unified, efficient, and extensible framework for robotic process automation (RPA). The protocol is designed for seamless integration across various automation tools and platforms while ensuring compatibility with mainstream standards.
---
## 开发文档
### JiuXin Intelligent Automation Protocol (JIAP) Developer Documentation
---
### Table of Contents
1. [Introduction](#1-introduction)
2. [System Architecture](#2-system-architecture)
3. [API Design and Communication Standards](#3-api-design-and-communication-standards)
4. [Modules and Methods](#4-modules-and-methods)
5. [Data Models](#5-data-models)
6. [Authentication and Security](#6-authentication-and-security)
7. [Error Handling](#7-error-handling)
8. [Extensibility](#8-extensibility)
9. [Examples and Use Cases](#9-examples-and-use-cases)
10. [FAQ](#10-faq)
---
## 1. Introduction
**JiuXin Intelligent Automation Protocol (JIAP)** provides a standardized framework for designing, executing, and managing RPA workflows. It aims to:
- Enable seamless integration across diverse systems.
- Simplify automation tasks through a unified interface.
- Ensure compatibility with mainstream RPA platforms and protocols.
Key Features:
- **Modularity**: Functional modules for file operations, data processing, system tasks, etc.
- **Extensibility**: Support for adding new modules and customizing workflows.
- **Compatibility**: Integration with RESTful APIs, WebSocket, and other widely adopted protocols.
- **Security**: Advanced authentication and encrypted data transmission.
---
## 2. System Architecture
### Core Components
1. **RPA Controller**:
- Manages task scheduling, robot orchestration, and resource allocation.
- Exposes APIs for external systems to interact with RPA workflows.
2. **Robot Agents**:
- Executes automation tasks assigned by the controller.
- Communicates with the controller to report task status and results.
3. **Activity Modules**:
- Encapsulated units for performing specific operations (e.g., file handling, Excel processing, database access).
- Easily extendable to accommodate new requirements.
4. **Logging and Monitoring System**:
- Records task execution logs.
- Provides insights into performance and troubleshooting information.
---
## 3. API Design and Communication Standards
### 3.1 Communication Protocols
- **RESTful API**:
- Base URL: `https://api.jiuxinai.com/v1/jiap`
- Used for synchronous task requests and query operations.
- **WebSocket**:
- URL: `wss://api.jiuxinai.com/ws`
- Supports asynchronous task execution and real-time communication.
### 3.2 Standard Request Format
```json
{
"method": "<module>.<operation>",
"params": {
"param1": "value1",
"param2": "value2"
}
}
```
### 3.3 Standard Response Format
```json
{
"status": "success", // success or error
"message": "Operation description",
"data": {
"key1": "value1",
"key2": "value2"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
## 4. Modules and Methods
### 4.1 File Operations Module
| Method | Description | Parameters |
|-------------------|------------------------|-----------------------------------------|
| `File.Copy` | Copy a file | `source_path`, `destination_path`, `overwrite` |
| `File.Delete` | Delete a file | `file_path` |
| `File.Rename` | Rename a file | `file_path`, `new_name` |
| `File.ListFiles` | List files in a folder | `directory_path`, `filter_by_extension` |
---
### 4.2 Excel Operations Module
| Method | Description | Parameters |
|-----------------------|------------------------------|--------------------------------------------|
| `Excel.ReadCell` | Read data from a cell | `file_path`, `sheet_name`, `cell_name`, `password` |
| `Excel.WriteCell` | Write data to a cell | `file_path`, `sheet_name`, `cell_name`, `value`, `password` |
| `Excel.MergeCells` | Merge or unmerge cells | `file_path`, `sheet_name`, `range_name`, `action` |
---
### 4.3 Network Module
| Method | Description | Parameters |
|---------------------|------------------------|---------------------------------|
| `Network.HttpGet` | Perform HTTP GET | `url`, `headers` |
| `Network.HttpPost` | Perform HTTP POST | `url`, `headers`, `body` |
| `Network.DownloadFile` | Download a file | `url`, `save_path` |
---
### 4.4 OCR Module
| Method | Description | Parameters |
|-----------------------|-----------------------------|---------------------------------|
| `OCR.ExtractText` | Extract text from an image | `image_path` |
| `OCR.ExtractFromPDF` | Extract text from a PDF | `pdf_path` |
---
### 4.5 Extended Modules
Additional modules such as database operations, system commands, and more can be added dynamically. See the extensibility section for details.
---
## 5. Data Models
### File Metadata Model
```json
{
"path": "/path/to/file.txt",
"size": 1024,
"created_at": "2024-04-01T10:00:00Z",
"modified_at": "2024-04-28T10:00:00Z"
}
```
### Excel Cell Data Model
```json
{
"file_path": "/path/to/excel.xlsx",
"sheet_name": "Sheet1",
"cell_name": "A1",
"value": "123"
}
```
---
## 6. Authentication and Security
### 6.1 Authentication
- **OAuth 2.0**:
- Obtain access tokens for API requests.
- Endpoint: `https://api.jiuxinai.com/auth/token`
- **API Key**:
- Simplified authentication for internal use cases.
### 6.2 Data Security
- Encrypted communication using HTTPS and WSS.
- Sensitive data (e.g., passwords) stored securely using industry-standard encryption.
---
## 7. Error Handling
Standardized error responses to ensure predictable and debuggable interactions.
### Example Error Response
```json
{
"status": "error",
"message": "File not found",
"data": null,
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
## 8. Extensibility
### Adding New Modules
1. Define the module and methods in the configuration file.
2. Implement the module logic in the backend.
3. Expose the module through the controller.
### Custom Operations
Developers can add custom workflows using configuration files or scripts, extending the protocol to meet specific needs.
---
## 9. Examples and Use Cases
### Example: File Copy Operation
**Request**:
```json
{
"method": "File.Copy",
"params": {
"source_path": "/source/file.txt",
"destination_path": "/destination/file.txt",
"overwrite": true
}
}
```
**Response**:
```json
{
"status": "success",
"message": "File copied successfully",
"data": {
"source_path": "/source/file.txt",
"destination_path": "/destination/file.txt",
"overwrite": true
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
## 10. FAQ
1. **How do I authenticate API requests?**
Use OAuth 2.0 tokens or API keys depending on your deployment.
2. **Can I integrate JIAP with other RPA platforms?**
Yes, JIAP is designed to be compatible with mainstream RPA tools through RESTful APIs.
---
This documentation provides a foundation for implementing and integrating **JIAP** in a wide range of automation scenarios. For more information, contact **JiuXin Intelligent Support** at [xiaoyigong@9xin.ai].

462
JIAP_Introducation.md Normal file
View File

@ -0,0 +1,462 @@
# 九鑫智能 RPA 协议与定义
## 1. 协议目标
- **统一性**：所有功能使用统一的接口、参数和返回值结构，保证一致性。
- **高效性**：设计轻量化的协议格式和高性能的执行方式，减少网络和系统资源开销。
- **可扩展性**：支持动态扩展新的功能模块和操作类型，兼容未来需求。
- **互操作性**：协议与主流 RPA 平台的 API 和方法兼容，便于集成。
- **安全性**：数据传输和存储中提供安全性保障，支持身份认证和权限控制。
---
## 2. 总体架构
```mermaid
graph TD
A[Client/用户] -->|API请求| B[RPA控制器]
B -->|任务分配| C[机器人代理]
C -->|调用| D[活动模块]
D -->|执行操作| C
C -->|任务结果| B
B -->|响应| A
B --> E[日志与监控系统]
C --> E
D --> E
```
### 2.1 系统组件
1. **RPA 控制器（Controller）**：
- 管理任务调度、运行状态监控。
- 提供 API 接口供客户端调用。
2. **RPA 机器人（Robot Agent）**：
- 执行具体任务的独立运行单元。
- 接收控制器的指令，调用底层操作模块完成任务。
3. **RPA 操作模块（Activity Modules）**：
- 独立的功能模块，每个模块对应特定任务类型（如文件操作、OCR、Excel 操作等）。
- 提供通用接口供机器人调用。
4. **日志与监控系统**：
- 实时记录任务状态、执行日志。
- 支持追溯与错误排查。
```mermaid
sequenceDiagram
participant Client as 客户端
participant Controller as 控制器
participant Robot as 机器人代理
participant Module as 活动模块
Client->>Controller: 发送任务请求
Controller->>Controller: 分析任务类型
Controller->>Robot: 分配任务
Robot->>Module: 调用相关操作模块
Module->>Robot: 返回操作结果
Robot->>Controller: 返回任务结果
Controller->>Client: 响应任务结果
```
---
### 2.2 数据流设计
1. **客户端请求**：
- 客户端通过 RESTful API 或 WebSocket 向控制器发送请求。
2. **任务调度**：
- 控制器接收请求后，根据任务类型和资源情况，将任务分配给适当的机器人。
3. **任务执行**：
- 机器人执行具体任务，并调用操作模块完成工作。
4. **结果返回**：
- 机器人将任务结果返回给控制器，由控制器统一响应客户端请求。
```mermaid
flowchart TD
A[客户端请求] -->|RESTful API/WebSocket| B[控制器]
B -->|任务调度| C[机器人代理]
C -->|调用活动模块| D[活动模块]
D -->|执行结果| C
C -->|任务结果| B
B -->|响应| E[客户端]
B --> F[日志与监控系统]
C --> F
D --> F
```
---
## 3. 接口协议规范
### 3.1 通信协议
- **协议类型**：支持 RESTful API（同步）和 WebSocket（异步）。
- **数据格式**：使用 JSON 作为数据交互格式，支持 UTF-8 编码。
### 3.2 API 基础结构
1. **基础 URL**：
- RESTful API 基础 URL: `https://api.jiuxinai.com/v1/rpa`
- WebSocket URL: `wss://api.jiuxinai.com/ws`
2. **HTTP 请求方法**：
- `GET`：查询资源。
- `POST`：创建资源或发送任务。
- `PUT`：更新资源。
- `DELETE`：删除资源。
3. **HTTP 状态码**：
- `200`：请求成功。
- `400`：客户端请求错误。
- `401`：认证失败。
- `404`：资源未找到。
- `500`：服务器错误。
---
## 4. 方法定义与参数
### 4.1 标准方法格式
所有方法名称采用统一格式：`<模块>.<操作>`，例如 `File.Copy`、`Excel.ReadCell`。
**接口格式**：
```json
{
"method": "<模块>.<操作>",
"params": {
"param1": "value1",
"param2": "value2"
}
}
```
**返回值格式**：
```json
{
"status": "success", // success 或 error
"message": "操作描述",
"data": {
// 返回的具体数据
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
### 4.2 功能模块定义
#### 文件操作模块
| 方法名 | 描述 | 参数 |
|-------------|-----------------------|-----------------------------------|
| File.Copy | 复制文件 | source_path, destination_path, overwrite |
| File.Delete | 删除文件 | file_path |
| File.Rename | 重命名文件 | file_path, new_name |
#### Excel 操作模块
| 方法名 | 描述 | 参数 |
|--------------------|----------------------|-----------------------------------|
| Excel.ReadCell | 读取 Excel 单元格值 | file_path, sheet_name, cell_name, password |
| Excel.WriteCell | 写入 Excel 单元格值 | file_path, sheet_name, cell_name, value, password |
| Excel.MergeCells | 合并单元格 | file_path, sheet_name, range_name, action |
#### 二维码模块
| 方法名 | 描述 | 参数 |
|-----------------------|-----------------------|-----------------------------------|
| QRCode.Generate | 生成二维码 | text, save_path, width, height |
| QRCode.Parse | 解析二维码 | file_path |
#### 时间模块
| 方法名 | 描述 | 参数 |
|--------------------|-----------------------|-----------|
| Time.GetCurrentTime| 获取当前时间 | 无 |
| Time.Format | 格式化时间 | time, format |
#### 网络请求模块
| 方法名 | 描述 | 参数 |
|------------------|-----------------------|-----------------------------------|
| Network.HttpGet | 发送 HTTP GET 请求 | url, headers |
| Network.HttpPost | 发送 HTTP POST 请求 | url, headers, body |
---
## 5. 数据模型定义
1. **文件模型**：
- **文件路径**：`path` (String)
- **文件大小**：`size` (Int)
- **创建时间**：`created_at` (String, ISO 8601)
- **修改时间**：`modified_at` (String, ISO 8601)
2. **Excel 单元格模型**：
- **单元格值**：`value` (String 或 Number)
- **工作表名称**：`sheet_name` (String)
- **单元格位置**：`cell_name` (String)
3. **二维码模型**：
- **文本内容**：`text` (String)
- **二维码路径**：`file_path` (String)
- **二维码大小**：`width`, `height` (Int)
---
## 6. 扩展能力
- **动态模块加载**：
- 使用插件机制动态加载新的功能模块，例如 OCR、数据库操作模块等。
- **自定义操作定义**：
- 支持用户通过配置文件自定义新的操作定义，增加灵活性。
---
## 7. 兼容性设计
- **主流 RPA 平台支持**：
- 方法命名参考主流平台（如 UiPath）保持一致，便于迁移。
- **协议兼容**：
- 使用开放协议（如 RESTful 和 WebSocket），确保与外部系统集成的便捷性。
- **多语言支持**：
- 数据交互统一采用 UTF-8 编码，支持多语言输入和输出。
---
## 8. 安全性规范
1. **身份认证**：
- 使用 OAuth2 或 JWT 进行访问控制。
2. **权限管理**：
- 基于角色（Role-Based Access Control, RBAC）设计权限。
3. **数据加密**：
- 传输过程中使用 HTTPS，敏感数据存储时加密。
---
## 9. 协议示例
### 任务请求示例
```json
{
"method": "File.Copy",
"params": {
"source_path": "/source/file.txt",
"destination_path": "/destination/file.txt",
"overwrite": true
}
}
```
### 返回值示例
```json
{
"status": "success",
"message": "文件复制成功",
"data": {
"source_path": "/source/file.txt",
"destination_path": "/destination/file.txt",
"overwrite": true
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
以下是扩展后的 RPA 功能模块设计，尽可能涵盖各类常见的 RPA 操作，包括文件管理、办公自动化、数据处理、网络操作、图像处理、系统操作等功能。每个模块都包含操作方法和对应的参数定义。
---
## 扩展后的功能模块
### 1. 文件操作模块
**描述**：提供文件管理相关操作。
| 方法名 | 描述 | 参数 |
|-------------------|--------------------------|---------------------------------------|
| File.Copy | 复制文件 | source_path, destination_path, overwrite |
| File.Delete | 删除文件 | file_path |
| File.Rename | 重命名文件 | file_path, new_name |
| File.Create | 创建新文件 | file_path, content |
| File.ReadContent | 读取文件内容 | file_path |
| File.WriteContent | 写入文件内容 | file_path, content, overwrite |
| File.ListFiles | 列出目录中的所有文件 | directory_path, filter_by_extension |
| File.GetInfo | 获取文件信息 | file_path |
---
### 2. 目录操作模块
**描述**：提供目录管理相关操作。
| 方法名 | 描述 | 参数 |
|---------------------|--------------------------|------------------------------------|
| Directory.Create | 创建目录 | directory_path |
| Directory.Delete | 删除目录（可递归删除） | directory_path, recursive |
| Directory.ListFiles | 列出目录中的文件 | directory_path |
| Directory.ListDirs | 列出子目录 | directory_path |
---
## 3. Excel 操作模块
**描述**：支持对 Excel 文件的各种操作。
| 方法名 | 描述 | 参数 |
|----------------------|--------------------------|-----------------------------------------|
| Excel.ReadCell | 读取 Excel 单元格值 | file_path, sheet_name, cell_name, password |
| Excel.WriteCell | 写入 Excel 单元格值 | file_path, sheet_name, cell_name, value, password |
| Excel.MergeCells | 合并或取消合并单元格 | file_path, sheet_name, range_name, action |
| Excel.ReadRange | 读取指定范围的单元格数据 | file_path, sheet_name, range_name |
| Excel.WriteRange | 写入指定范围的单元格数据 | file_path, sheet_name, range_name, values |
| Excel.AddSheet | 添加新的工作表 | file_path, sheet_name |
| Excel.DeleteSheet | 删除指定的工作表 | file_path, sheet_name |
| Excel.ListSheets | 列出所有工作表 | file_path |
---
### 4. Word 操作模块
**描述**：支持对 Word 文档的各种操作。
| 方法名 | 描述 | 参数 |
|--------------------------|--------------------------|----------------------------------|
| Word.ReadContent | 读取文档内容 | file_path, visible |
| Word.WriteContent | 写入文档内容 | file_path, content, overwrite |
| Word.ReplaceText | 替换文档中的指定文本 | file_path, find_text, replace_text |
| Word.AddTable | 向文档添加表格 | file_path, rows, columns |
| Word.AddImage | 向文档插入图片 | file_path, image_path, position |
| Word.CloseDocument | 关闭文档 | file_path, visible |
---
### 5. 图像处理模块
**描述**：支持对图像的基本处理操作。
| 方法名 | 描述 | 参数 |
|------------------------|--------------------------|------------------------------------|
| Image.Resize | 调整图像大小 | image_path, width, height |
| Image.ConvertFormat | 转换图像格式 | image_path, target_format |
| Image.Rotate | 旋转图像 | image_path, angle |
| Image.Crop | 裁剪图像 | image_path, x, y, width, height |
| Image.AddWatermark | 向图像添加水印 | image_path, watermark_text, position |
| Image.ParseQRCode | 从图像解析二维码 | image_path |
| Image.GenerateQRCode | 生成二维码图像 | content, save_path, size |
---
### 6. 压缩与解压模块
**描述**：支持文件或目录的压缩与解压缩。
| 方法名 | 描述 | 参数 |
|-------------------------|--------------------------|------------------------------------|
| Archive.Compress | 压缩文件或目录 | source_paths, output_path, format |
| Archive.Decompress | 解压缩文件 | archive_path, destination_path |
---
### 7. 网络操作模块
**描述**：支持 HTTP 请求和网络下载功能。
| 方法名 | 描述 | 参数 |
|----------------------|--------------------------|----------------------------------|
| Network.HttpGet | 发送 HTTP GET 请求 | url, headers |
| Network.HttpPost | 发送 HTTP POST 请求 | url, headers, body |
| Network.DownloadFile | 下载文件 | url, save_path |
---
### 8. 数据库操作模块
**描述**：支持基本的数据库查询和修改操作。
| 方法名 | 描述 | 参数 |
|-------------------------|--------------------------|--------------------------------------|
| Database.Connect | 连接数据库 | connection_string |
| Database.ExecuteQuery | 执行 SQL 查询 | query, parameters |
| Database.Insert | 插入数据 | table_name, data |
| Database.Update | 更新数据 | table_name, data, condition |
| Database.Delete | 删除数据 | table_name, condition |
---
### 9. 系统操作模块
**描述**：提供系统级别的操作功能。
| 方法名 | 描述 | 参数 |
|------------------------|--------------------------|------------------------------------|
| System.GetEnvironment | 获取环境变量 | variable_name |
| System.SetEnvironment | 设置环境变量 | variable_name, value |
| System.ExecuteCommand | 执行系统命令 | command |
| System.GetSystemInfo | 获取系统信息 | 无 |
---
### 10. 时间与日期模块
**描述**：支持时间和日期的处理操作。
| 方法名 | 描述 | 参数 |
|-----------------------|--------------------------|------------------------------------|
| Time.GetCurrentTime | 获取当前时间 | 无 |
| Time.AddTime | 时间加减运算 | base_time, delta, unit |
| Time.FormatTime | 格式化时间 | time, format |
---
### 11. OCR（光学字符识别）模块
**描述**：提供 OCR 操作，支持从图像中提取文本。
| 方法名 | 描述 | 参数 |
|------------------------|--------------------------|------------------------------------|
| OCR.ExtractText | 从图像中提取文本 | image_path |
| OCR.ExtractFromPDF | 从 PDF 文件提取文本 | pdf_path |
---
### 12. 邮件操作模块
**描述**：支持邮件发送和接收操作。
| 方法名 | 描述 | 参数 |
|------------------------|--------------------------|------------------------------------|
| Email.SendEmail | 发送邮件 | to, subject, body, attachments |
| Email.ReceiveEmails | 接收邮件 | email_address, password, filters |
---
### 13. API 集成模块
**描述**：提供对外部 API 的集成能力。
| 方法名 | 描述 | 参数 |
|----------------------|--------------------------|----------------------------------|
| API.Call | 调用外部 API | endpoint, method, headers, body |
---
### 14. 文件传输模块
**描述**：支持文件的上传与下载。
| 方法名 | 描述 | 参数 |
|------------------------|--------------------------|------------------------------------|
| FileTransfer.Upload | 上传文件到远程服务器 | file_path, server_url, credentials |
| FileTransfer.Download | 从远程服务器下载文件 | file_url, save_path, credentials |
---
### 扩展说明
这套设计包含了常见的企业自动化场景，涵盖文件管理、办公自动化、网络操作、系统操作、数据库管理、图像处理等模块。每个模块提供了基础操作和扩展能力，能够满足大部分 RPA 的功能需求，并为未来的业务需求扩展提供了良好的基础。

225
README.md Normal file
View File

@ -0,0 +1,225 @@
# RPA Chat API 文档
## 项目简介
本项目是一个基于 **FastAPI** 和 **OpenAI GPT 模型** 的聊天接口服务。该服务实现了一个 **RPA（机器人流程自动化）助手**，根据用户的输入生成标准化的 RPA 操作命令，并通过 JSON 格式返回响应。
---
## 功能概述
1. **与 OpenAI GPT 模型交互**
- 用户输入文本，服务会通过 OpenAI API 与 GPT 模型交互，生成相应的 RPA 命令。
2. **标准化 RPA 命令输出**
- 支持生成多种 RPA 命令（如文件操作、Excel 操作、二维码生成等），并以标准的 JSON 格式返回。
3. **会话管理**
- 支持维护对话历史记录，通过日志文件保存用户与 AI 的交互内容。
4. **API 端点**
- 提供聊天、获取会话历史、清除会话历史的 REST API。
---
## 目录结构
```plaintext
project/
│
├── rpa_api.py # API 服务器代码
├── rpa_client.py # 客户端配置和 RPA 系统提示
├── rpa_conversation.log # 会话日志文件
├── requirements.txt # 依赖包列表
└── README.md # 项目文档
```
---
## 安装与运行
### 1. 环境准备
确保已安装 **Python 3.8+** 和 **pip**。
### 2. 安装依赖
执行以下命令安装必要的依赖包：
```bash
pip install -r requirements.txt
```
### 3. 配置 OpenAI API
- 在 `rpa_client.py` 中替换为你的 OpenAI API 密钥和 GPT 服务地址：
```python
api_key = "your-openai-api-key" # 替换为您的 OpenAI API 密钥
base_url = "http://52.90.243.11:8787/v1" # OpenAI 服务地址
```
### 4. 启动 API 服务
运行以下命令启动 FastAPI 服务器：
```bash
python rpa_api.py
```
服务器默认运行在 `http://0.0.0.0:11089`。
---
## API 文档
### 1. 聊天接口（POST）
**路径**：`/chat`
**描述**：接收用户消息，与 OpenAI GPT 模型交互，返回 RPA 命令。
#### 请求参数
- **message** *(必填)*：用户输入的消息文本。
- **allowed_paths** *(可选)*：指定文件操作允许的路径。
示例请求：
```json
{
"message": "请复制文件A到路径B。",
"allowed_paths": "/allowed/directory"
}
```
#### 响应参数
- **response**：GPT 的自然语言回复。
- **commands**：生成的 RPA 命令列表。
示例响应：
```json
{
"response": "好的，文件已准备复制。",
"commands": [
{
"command": "Lan.Core.Activities.Copy",
"parameters": {
"SourceFilePath": "/path/to/fileA",
"TargetFilePath": "/path/to/destination",
"Overwrite": "是"
}
}
]
}
```
---
### 2. 获取会话历史（GET）
**路径**：`/conversations/{conversation_id}`
**描述**：获取指定会话的历史记录。
#### 请求参数
- **conversation_id** *(必填)*：会话唯一标识符。
#### 示例响应
```json
[
{"role": "system", "content": "您是一名RPA助手..."},
{"role": "user", "content": "请复制文件A到路径B。"},
{"role": "assistant", "content": "好的，文件已准备复制。"}
]
```
---
### 3. 清除会话历史（DELETE）
**路径**：`/conversations/{conversation_id}`
**描述**：清除指定会话的历史记录，保留系统提示。
#### 示例响应
```json
{
"status": "success"
}
```
---
## RPA 命令列表
本项目支持的 RPA 命令包括：
1. **文件复制**：`Lan.Core.Activities.Copy`
2. **读取 Excel 单元格**：`Lan.Office.Activities.Excel.ReadCell`
3. **写入 Excel 单元格**：`Lan.Office.Activities.Excel.WriteCell`
4. **合并/取消合并单元格**：`Lan.Office.Activities.Excel.MergeRange`
5. **关闭 Word 文档**：`Lan.OfficeCom.Activities.CloseDocument`
6. **读取 Word 文档内容**：`Lan.OfficeCom.Activities.ReadDocumentText`
7. **生成二维码**：`Lan.Integration.Activities.GenerateQRCode`
8. **解析二维码**：`Lan.Integration.Activities.ParsingQRCode`
9. **ASCII 转字符串**：`Lan.Core.Activities.ASCIIToString`
10. **字符串转 ASCII**：`Lan.Core.Activities.StringToASCII`
---
## 日志记录
- 服务端交互日志会记录在 `rpa_conversation.log` 文件中。
- 日志示例：
```plaintext
2024-04-28 12:00:00 - INFO - User: 请复制文件A到路径B。
2024-04-28 12:00:01 - INFO - Assistant: 好的，文件已准备复制。
2024-04-28 12:00:01 - INFO - Commands: [{"command": "Lan.Core.Activities.Copy", "parameters": {"SourceFilePath": "/path/to/fileA", "TargetFilePath": "/path/to/destination"}}]
```
---
## 测试示例
使用工具如 **Postman** 或 `curl` 测试 API：
### 测试 `/chat`
```bash
curl -X POST "http://0.0.0.0:11089/chat" \
-H "Content-Type: application/json" \
-d '{"message": "请复制文件A到路径B。"}'
```
---
## 依赖库
- **FastAPI**：Web 框架。
- **OpenAI**：与 GPT 模型交互的库。
- **Pydantic**：数据验证。
- **Uvicorn**：ASGI 服务器。
安装依赖：
```bash
pip install fastapi uvicorn pydantic openai
```
---
## 注意事项
1. **API 密钥保护**：请确保 API 密钥安全，不要在公共环境中泄露。
2. **系统提示更新**：`rpa_client.py` 中的 `rpa_prompt` 可以根据具体 RPA 需求进行调整。
3. **路径访问安全**：`allowed_paths` 参数可用于限制文件操作的访问路径。
---
## 许可证
本项目基于 [MIT License](https://opensource.org/licenses/MIT)。

172
rpa_api.py Normal file
View File

@ -0,0 +1,172 @@
import logging
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from typing import List, Optional
from openai import OpenAI
import json
import os
from rpa_client import rpa_prompt, api_key, base_url
# 配置日志
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s [%(levelname)s] %(message)s'
)
logger = logging.getLogger(__name__)
# 配置对话日志
conversation_logger = logging.getLogger('conversation_logger')
conversation_logger.setLevel(logging.INFO)
file_handler = logging.FileHandler('rpa_conversation.log')
file_handler.setLevel(logging.INFO)
formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
file_handler.setFormatter(formatter)
conversation_logger.addHandler(file_handler)
# 初始化 FastAPI 应用
app = FastAPI(title="RPA Chat API")
# 配置 CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# 初始化 OpenAI 客户端
client = OpenAI(api_key=api_key, base_url=base_url)
# 请求模型
class ChatRequest(BaseModel):
message: str
allowed_paths: Optional[str] = None
# 响应模型
class ChatResponse(BaseModel):
response: str
commands: List[dict]
# 存储对话历史的字典
conversations = {}
def get_conversation_history(conversation_id: str) -> list:
"""获取或创建对话历史"""
if conversation_id not in conversations:
# 初始化新的对话，包含系统提示
conversations[conversation_id] = [
{
"role": "system",
"content": rpa_prompt
}
]
return conversations[conversation_id]
async def interact_with_chatgpt(messages: list) -> str:
"""与 ChatGPT 交互"""
try:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
max_tokens=500,
temperature=0.1,
)
return response.choices[0].message.content
except Exception as e:
logger.error(f"OpenAI API 调用错误: {e}")
raise
def parse_chatgpt_response(response_text: str) -> tuple[str, list]:
"""解析 ChatGPT 的响应"""
try:
# 清理响应文本
response_text = response_text.strip()
if response_text.startswith("```json"):
response_text = response_text.replace("```json", "", 1)
if response_text.endswith("```"):
response_text = response_text.replace("```", "", 1)
# 解析 JSON
data = json.loads(response_text.strip())
return data["response"], data.get("commands", [])
except Exception as e:
logger.error(f"解析响应失败: {e}")
return "解析响应时出错", []
@app.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
"""处理聊天请求"""
try:
# 生成会话ID (这里简单使用固定ID，您可以根据需要修改)
conversation_id = "default"
# 获取对话历史
messages = get_conversation_history(conversation_id)
# # 如果提供了新的允许路径，更新系统提示
# if request.allowed_paths:
# messages[0]["content"] = rpa_prompt.replace(
# "{allowed_paths}",
# request.allowed_paths
# )
# 添加用户消息
messages.append({
"role": "user",
"content": request.message
})
# 保持对话历史在合理长度
if len(messages) > 10:
# 保留系统消息和最近的对话
messages = [messages[0]] + messages[-9:]
# 记录对话
conversation_logger.info(f"User: {request.message}")
# 调用 ChatGPT
chatgpt_response = await interact_with_chatgpt(messages)
# 解析响应
response_text, commands = parse_chatgpt_response(chatgpt_response)
# 记录响应
conversation_logger.info(f"Assistant: {response_text}")
conversation_logger.info(f"Commands: {commands}")
# 添加助手响应到对话历史
messages.append({
"role": "assistant",
"content": chatgpt_response
})
return ChatResponse(
response=response_text,
commands=commands
)
except Exception as e:
logger.error(f"处理请求时出错: {e}")
raise HTTPException(status_code=500, detail=str(e))
@app.get("/conversations/{conversation_id}")
async def get_conversation(conversation_id: str):
"""获取对话历史"""
if conversation_id not in conversations:
raise HTTPException(status_code=404, detail="Conversation not found")
return conversations[conversation_id]
@app.delete("/conversations/{conversation_id}")
async def clear_conversation(conversation_id: str):
"""清除对话历史"""
if conversation_id in conversations:
# 保留系统提示
system_prompt = conversations[conversation_id][0]
conversations[conversation_id] = [system_prompt]
return {"status": "success"}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=11089)

115
rpa_client.py Normal file
View File

@ -0,0 +1,115 @@
# API配置
api_key = "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" # 替换为您的 OpenAI API 密钥
base_url = "http://52.90.243.11:8787/v1"
rpa_prompt = """
您是一名RPA（机器人流程自动化）助手，根据用户的请求生成RPA操作命令。
您可以生成以下命令：
1. `Lan.Core.Activities.Copy`：可对文件进行复制操作并粘贴到指定的文件路径下。
- 参数：
- `SourceFilePath` (String)：输入原始文件全路径。
- `TargetFilePath` (String)：输入粘贴后的文件路径。
- `TargetFileName` (String, 可选)：输入粘贴后的文件名称，不填写默认与原文件名称一致。
- `Overwrite` (Boolean)：选择是否需要进行覆盖操作，可选择“是”或“否”。
2. `Lan.Office.Activities.Excel.ReadCell`：提取指定的单元格值。
- 参数：
- `CellName` (String)：输入需要提取值的单元格名称。
- `SheetName` (String)：输入需要提取的工作表名称。
- `Password` (String, 可选)：输入对应Excel表的密码。
- `FilePath` (String)：输入需要提取单元格的Excel表的文件路径。
- `CellValue` (Object)：定义一个变量接收提取到的单元格值。
3. `Lan.Office.Activities.Excel.WriteCell`：在指定单元格写入单元格值。
- 参数：
- `CellName` (String)：输入需要写入的单元格名称。
- `SheetName` (String)：输入需要写入值的工作表名称。
- `Password` (String, 可选)：输入对应Excel表的密码。
- `FilePath` (String)：输入需要写入值的Excel文件路径。
- `CellContent` (Object)：输入需要写入单元格的值。
4. `Lan.Office.Activities.Excel.MergeRange`：可对选定的单元格进行合并或取消合并操作。
- 参数：
- `RangeName` (String)：输入需要进行合并或取消合并的单元格区域。
- `SheetName` (String)：输入需要进行单元格合并或取消的工作表名称。
- `Password` (String, 可选)：输入对应Excel表的密码。
- `FilePath` (String)：输入需要执行单元格合并或取消的Excel文件路径。
- `Option` (MergeOperation)：选择“合并单元格”或“取消合并单元格”。
5. `Lan.OfficeCom.Activities.CloseDocument`：关闭指定路径下的Word文档。
- 参数：
- `Visible` (Boolean)：选择对应的Word文档是否可见。
- `FilePath` (String)：输入需要关闭的Word文档路径。
6. `Lan.OfficeCom.Activities.ReadDocumentText`：读取指定文档内容。
- 参数：
- `Visible` (Boolean)：选择对应的Word文档是否可见。
- `FilePath` (String)：输入需要读取的Word文档路径。
- `Content` (String)：定义一个变量接收读取到的文档内容。
7. `Lan.Integration.Activities.GenerateQRCode`：将输入的字符串生成二维码图像并保存到指定目录。
- 参数：
- `SaveFilePath` (String)：输入保存二维码图像的文件路径，需要带上对应的格式，例如：jpg。
- `Height` (Int32)：输入二维码图像的高度。
- `Width` (Int32)：输入二维码图像的宽度。
- `Text` (String)：输入存储在二维码中的数据，可以是文本、URL等。
8. `Lan.Integration.Activities.ParsingQRCode`：解析指定二维码图像中的文本数据。
- 参数：
- `SaveFilePath` (String)：输入需要解析的二维码图像的文件路径。
- `Text` (String)：定义一个变量接收从二维码图像中解析出来的文本数据。
9. `Lan.Core.Activities.ASCIIToString`：根据输入的ASCII转换为字符格式。
- 参数：
- `ASCLLCode` (String)：输入需要转换成字符的ASCII字符。
- `Result` (String)：定义一个变量接收转换完成的字符串。
10. `Lan.Core.Activities.StringToASCII`：将指定字符串转换为ASCII。
- 参数：
- `Str` (String)：输入需要转换为ASCII的字符串。
- `TranString` (String)：定义一个变量接收转换后的ASCII值。
当生成响应时，始终以以下JSON格式返回，包含一个"response"字段和一个"commands"数组。即使只有一个命令，`commands`数组也应包含一个元素：
```json
{
"response": "<对用户的回复，例如'好的，我记住了这个信息。'>",
"commands": [
{
"command": "<command_name>",
"parameters": {
"<parameter_name>": "<value>",
...
}
}
]
}
如果需要链式执行多个命令，commands数组中包含多个命令对象：
```json
{
"response": "<对用户的回复>",
"commands": [
{
"command": "<command_name_1>",
"parameters": {
"<parameter_name>": "<value>",
...
}
},
{
"command": "<command_name_2>",
"parameters": {
"<parameter_name>": "<value>",
...
}
}
]
}
```
请确保您的回复严格遵守上述格式，不要包含额外的文本或解释。
"""

411
suggest.md Normal file
View File

@ -0,0 +1,411 @@
# RPA 函数规范化定义建议
以下是经过规范化和统一化后的 RPA 函数定义。主要规范化的方面包括：
1. **方法名**：统一为驼峰命名法，前缀统一为模块名（`Lan`）+ 功能描述 + 动作。
2. **参数名**：统一使用小写字母+下划线命名法。
3. **可选参数**：明确标注可选参数，并使用一致的命名和格式。
4. **参数命名与描述**：确保参数名简洁、描述一致且直观。
5. **返回值统一**：移除冗余的变量接收参数，通过响应中返回。
---
### 规范化后的定义
#### 1. 文件复制操作
```plaintext
**方法名**：Lan.Core.CopyFile
**描述**：复制文件并粘贴到指定目标路径。
**参数**：
- source_file_path (String, 必填)：原始文件的完整路径。
- target_file_path (String, 必填)：目标文件夹路径。
- target_file_name (String, 可选)：目标文件名，默认使用原始文件名。
- overwrite (Boolean, 必填)：是否覆盖目标路径中的同名文件。可选值：true/false。
```
---
#### 2. 读取 Excel 单元格
```plaintext
**方法名**：Lan.Excel.ReadCell
**描述**：读取 Excel 表格中指定单元格的内容。
**参数**：
- file_path (String, 必填)：Excel 文件的完整路径。
- sheet_name (String, 必填)：工作表名称。
- cell_name (String, 必填)：单元格名称（如 A1、B2）。
- password (String, 可选)：Excel 文件密码。
```
---
#### 3. 写入 Excel 单元格
```plaintext
**方法名**：Lan.Excel.WriteCell
**描述**：向 Excel 表格中指定单元格写入内容。
**参数**：
- file_path (String, 必填)：Excel 文件的完整路径。
- sheet_name (String, 必填)：工作表名称。
- cell_name (String, 必填)：单元格名称（如 A1、B2）。
- cell_value (Object, 必填)：要写入的内容。
- password (String, 可选)：Excel 文件密码。
```
---
#### 4. 合并/取消合并单元格
```plaintext
**方法名**：Lan.Excel.MergeCells
**描述**：合并或取消合并 Excel 表格中的单元格。
**参数**：
- file_path (String, 必填)：Excel 文件的完整路径。
- sheet_name (String, 必填)：工作表名称。
- range_name (String, 必填)：单元格区域名称（如 A1:C3）。
- option (String, 必填)：操作类型，可选值："merge"（合并）或 "unmerge"（取消合并）。
- password (String, 可选)：Excel 文件密码。
```
---
#### 5. 关闭 Word 文档
```plaintext
**方法名**：Lan.Word.CloseDocument
**描述**：关闭指定路径下的 Word 文档。
**参数**：
- file_path (String, 必填)：Word 文档的完整路径。
- visible (Boolean, 必填)：文档是否可见。可选值：true/false。
```
---
#### 6. 读取 Word 文档内容
```plaintext
**方法名**：Lan.Word.ReadDocument
**描述**：读取 Word 文档中的所有文本内容。
**参数**：
- file_path (String, 必填)：Word 文档的完整路径。
- visible (Boolean, 必填)：文档是否可见。可选值：true/false。
```
---
#### 7. 生成二维码
```plaintext
**方法名**：Lan.QRCode.Generate
**描述**：将输入文本生成二维码图像并保存到指定路径。
**参数**：
- save_file_path (String, 必填)：二维码图像的保存路径（需指定格式，如 example.jpg）。
- text (String, 必填)：要存储在二维码中的文本或 URL。
- width (Int, 必填)：二维码图像的宽度。
- height (Int, 必填)：二维码图像的高度。
```
---
#### 8. 解析二维码
```plaintext
**方法名**：Lan.QRCode.Parse
**描述**：解析二维码图像并提取其中的文本数据。
**参数**：
- file_path (String, 必填)：二维码图像的完整路径。
```
---
#### 9. ASCII 转字符串
```plaintext
**方法名**：Lan.Core.ASCIIToString
**描述**：将 ASCII 编码转换为字符串。
**参数**：
- ascii_code (String, 必填)：需要转换的 ASCII 编码字符串。
```
---
#### 10. 字符串转 ASCII
```plaintext
**方法名**：Lan.Core.StringToASCII
**描述**：将字符串转换为 ASCII 编码格式。
**参数**：
- input_string (String, 必填)：需要转换的字符串。
```
---
### 规范总结
1. **方法名**：采用模块前缀（如 `Lan.Core`、`Lan.Excel`）+ 功能描述 + 动作，保持一致。
2. **参数命名**：统一为小写字母+下划线的命名方式，确保易读和规范。
3. **参数顺序**：必填参数在前，可选参数在后。
4. **参数类型**：明确标注类型（如 String、Boolean、Int）。
5. **选项值标准化**：将布尔值统一为 `true/false`，其他选项如操作类型明确约束（如 "merge"、"unmerge"）。
6. **描述**：方法描述简洁清晰，参数的功能和用法明确统一。
## 返回值
以下是为 RPA 函数定义提供的**统一规范返回值**。返回值结构简洁、统一，确保每个方法在执行后能够清晰地传达执行状态、结果和相关信息。
### 返回值统一格式
所有函数返回值将遵循以下 JSON 格式：
```json
{
"status": "success", // 执行状态: success / error
"message": "操作成功", // 简要描述执行结果
"data": { // 执行结果的具体数据
"key": "value"
},
"timestamp": "2024-04-28T12:00:00Z" // 服务器响应的时间戳
}
```
#### 字段解释：
1. **status**：
- `success`：操作成功。
- `error`：操作失败。
2. **message**：简要描述执行结果的文本信息。
3. **data**：返回的具体数据，结构根据方法的实际执行结果而定。
4. **timestamp**：操作完成的时间，ISO8601 格式。
---
### 各方法返回值定义
#### 1. 文件复制操作 - `Lan.Core.CopyFile`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "文件复制成功",
"data": {
"source_file_path": "/path/to/source/fileA.txt",
"target_file_path": "/path/to/destination/fileA_copy.txt",
"overwrite": true
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
### 2. 读取 Excel 单元格 - `Lan.Excel.ReadCell`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "单元格读取成功",
"data": {
"file_path": "/path/to/excel.xlsx",
"sheet_name": "Sheet1",
"cell_name": "A1",
"cell_value": "123"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
#### 3. 写入 Excel 单元格 - `Lan.Excel.WriteCell`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "单元格写入成功",
"data": {
"file_path": "/path/to/excel.xlsx",
"sheet_name": "Sheet1",
"cell_name": "A1",
"cell_value": "Hello World"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
### 4. 合并/取消合并单元格 - `Lan.Excel.MergeCells`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "单元格合并成功",
"data": {
"file_path": "/path/to/excel.xlsx",
"sheet_name": "Sheet1",
"range_name": "A1:C3",
"operation": "merge"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
#### 5. 关闭 Word 文档 - `Lan.Word.CloseDocument`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "Word 文档关闭成功",
"data": {
"file_path": "/path/to/document.docx",
"visible": false
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
### 6. 读取 Word 文档内容 - `Lan.Word.ReadDocument`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "文档读取成功",
"data": {
"file_path": "/path/to/document.docx",
"content": "这是文档的全部内容。"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
#### 7. 生成二维码 - `Lan.QRCode.Generate`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "二维码生成成功",
"data": {
"save_file_path": "/path/to/qrcode.jpg",
"text": "https://example.com",
"width": 200,
"height": 200
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
#### 8. 解析二维码 - `Lan.QRCode.Parse`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "二维码解析成功",
"data": {
"file_path": "/path/to/qrcode.jpg",
"text": "https://example.com"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
#### 9. ASCII 转字符串 - `Lan.Core.ASCIIToString`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "ASCII 转换成功",
"data": {
"ascii_code": "65 66 67",
"result": "ABC"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
#### 10. 字符串转 ASCII - `Lan.Core.StringToASCII`
##### 返回值示例（成功）：
```json
{
"status": "success",
"message": "字符串转换为 ASCII 成功",
"data": {
"input_string": "ABC",
"ascii_code": "65 66 67"
},
"timestamp": "2024-04-28T12:00:00Z"
}
```
---
#### 统一错误返回值示例
如果操作失败，返回以下格式的错误信息：
```json
{
"status": "error",
"message": "文件路径不存在",
"data": null,
"timestamp": "2024-04-28T12:00:00Z"
}
```
#### 字段说明：
1. **status**：`error` 表示操作失败。
2. **message**：包含错误原因的简要描述。
3. **data**：失败时为 `null`。
4. **timestamp**：错误发生的时间。
---
## 总结
### 统一规范总结：
1. **方法返回值**：统一格式，包含 `status`、`message`、`data` 和 `timestamp` 字段。
2. **成功返回**：返回详细的操作数据，易于跟踪和验证。
3. **失败返回**：提供明确的错误消息，方便调试和处理。
4. **一致性**：所有方法均遵循相同的返回值结构，增强了接口的可维护性和标准化。