From c036c8c1684b1b79c6b70bc1a6f4cf37de790339 Mon Sep 17 00:00:00 2001 From: fatsand Date: Thu, 19 Dec 2024 10:15:23 +0800 Subject: [PATCH] first commit --- JIAP_Develop.md | 546 ++++++++++++++++++++++++++++++++++++++++++ JIAP_Introducation.md | 462 +++++++++++++++++++++++++++++++++++ README.md | 225 +++++++++++++++++ rpa_api.py | 172 +++++++++++++ rpa_client.py | 115 +++++++++ suggest.md | 411 +++++++++++++++++++++++++++++++ 6 files changed, 1931 insertions(+) create mode 100644 JIAP_Develop.md create mode 100644 JIAP_Introducation.md create mode 100644 README.md create mode 100644 rpa_api.py create mode 100644 rpa_client.py create mode 100644 suggest.md diff --git a/JIAP_Develop.md b/JIAP_Develop.md new file mode 100644 index 0000000..8a2b3b1 --- /dev/null +++ b/JIAP_Develop.md @@ -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": ".", + "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]. \ No newline at end of file diff --git a/JIAP_Introducation.md b/JIAP_Introducation.md new file mode 100644 index 0000000..184aeca --- /dev/null +++ b/JIAP_Introducation.md @@ -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 的功能需求,并为未来的业务需求扩展提供了良好的基础。 \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..338a598 --- /dev/null +++ b/README.md @@ -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)。 \ No newline at end of file diff --git a/rpa_api.py b/rpa_api.py new file mode 100644 index 0000000..14f9e2e --- /dev/null +++ b/rpa_api.py @@ -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) \ No newline at end of file diff --git a/rpa_client.py b/rpa_client.py new file mode 100644 index 0000000..85d4b98 --- /dev/null +++ b/rpa_client.py @@ -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": "", + "parameters": { + "": "", + ... + } + } + ] +} + +如果需要链式执行多个命令,commands数组中包含多个命令对象: + +```json +{ + "response": "<对用户的回复>", + "commands": [ + { + "command": "", + "parameters": { + "": "", + ... + } + }, + { + "command": "", + "parameters": { + "": "", + ... + } + } + ] +} +``` + +请确保您的回复严格遵守上述格式,不要包含额外的文本或解释。 +""" \ No newline at end of file diff --git a/suggest.md b/suggest.md new file mode 100644 index 0000000..5b2dc66 --- /dev/null +++ b/suggest.md @@ -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. **一致性**:所有方法均遵循相同的返回值结构,增强了接口的可维护性和标准化。 \ No newline at end of file