diff --git a/purexiao/huoban-api-suite/CONTRIBUTING.md b/purexiao/huoban-api-suite/CONTRIBUTING.md new file mode 100644 index 000000000..d34b6d3eb --- /dev/null +++ b/purexiao/huoban-api-suite/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contributing to Huoban Dify Plugin + +Thank you for your interest in contributing to the Huoban Dify Plugin! This document provides guidelines and instructions for contributing. + +## Code of Conduct + +Please be respectful and considerate of others when contributing to this project. + +## How to Contribute + +### Reporting Issues +1. Check if the issue already exists in the issue tracker +2. Use the issue template if available +3. Provide detailed information: + - Steps to reproduce + - Expected behavior + - Actual behavior + - Screenshots if applicable + - Dify version and environment details + +### Feature Requests +1. Explain the feature and its use case +2. Describe the expected behavior +3. Consider if it aligns with the plugin's scope + +### Pull Requests +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +## Development Setup + +### Prerequisites +- Node.js 16+ (for testing) +- Dify development environment +- Huoban API access + +### Local Development +1. Clone the repository +2. Install dependencies (if any) +3. Make your changes +4. Test locally with Dify + +### Testing +- Test all API endpoints with sample data +- Verify error handling +- Ensure compatibility with Dify's plugin system +- Test with different Huoban workspace configurations + +## Code Guidelines + +### OpenAPI Specification +- Follow OpenAPI 3.1.0 standards +- Include comprehensive descriptions for all operations +- Provide clear examples +- Document all parameters and responses + +### Manifest File +- Keep `manifest.json` up to date +- Include proper localization (en_US and zh_Hans) +- Update version numbers appropriately +- Maintain accurate metadata + +### Documentation +- Update README.md with new features +- Include usage examples +- Document breaking changes +- Keep changelog updated + +## Release Process + +1. Update version in `manifest.json` +2. Update changelog in README.md +3. Create release notes +4. Tag the release +5. Submit to Dify Marketplace + +## Questions? + +Feel free to open an issue for questions about contributing or development. + +## License + +By contributing, you agree that your contributions will be licensed under the MIT License. diff --git a/purexiao/huoban-api-suite/DIFY_MARKETPLACE_CHECKLIST.md b/purexiao/huoban-api-suite/DIFY_MARKETPLACE_CHECKLIST.md new file mode 100644 index 000000000..538ef500d --- /dev/null +++ b/purexiao/huoban-api-suite/DIFY_MARKETPLACE_CHECKLIST.md @@ -0,0 +1,142 @@ +# Dify Marketplace 发布检查清单 + +## ✅ 已完成的工作 + +### 1. 核心文件结构 +- [x] `manifest.json` - 完整的插件清单，包含所有必需字段 +- [x] `openapi.json` - 完整的OpenAPI 3.1.0规范（从原始文件复制） +- [x] `README.md` - 详细的用户文档，包含安装、使用、示例 +- [x] `PRIVACY.md` - 完整的隐私政策文档 +- [x] `LICENSE` - MIT许可证文件 +- [x] `huoban-plugin-dify.zip` - 插件压缩包 + +### 2. manifest.json 配置 +- [x] schema_version: "1.0" +- [x] type: "tool" +- [x] namespace: "huoban" +- [x] 多语言名称 (en_US, zh_Hans) +- [x] 多语言描述 (en_US, zh_Hans) +- [x] 图标和背景颜色 +- [x] 作者信息 (author, author_url) +- [x] 版本管理 (version: "1.2.0") +- [x] 标签和分类 +- [x] 主页和仓库链接 +- [x] 许可证信息 +- [x] OpenAPI引用 +- [x] API密钥认证配置 +- [x] 隐私政策链接 +- [x] 支持链接 +- [x] 发布说明 +- [x] 数据收集声明 + +### 3. OpenAPI 规范 +- [x] 完整的9个API端点 +- [x] 工作区管理 (get_workspace_list) +- [x] 表格操作 (get_table_list, get_table_config) +- [x] 数据CRUD (create_record, query_table_data, get_item_detail, update_record, delete_record) +- [x] 成员管理 (get_space_members) +- [x] API密钥认证 (Bearer token) +- [x] 详细的参数和响应模式 +- [x] 错误处理定义 + +### 4. 文档和用户指南 +- [x] 功能概述 +- [x] 安装说明 (Dify Marketplace和手动安装) +- [x] 认证配置 +- [x] 工具详细说明 (9个工具) +- [x] 使用示例和最佳实践 +- [x] 字段ID映射系统说明 +- [x] 错误处理和故障排除 +- [x] 支持资源和联系方式 +- [x] 更新日志 +- [x] 贡献指南 + +### 5. 合规性和安全性 +- [x] 隐私政策文档 +- [x] 数据收集声明 (不收集用户数据) +- [x] HTTPS加密传输 +- [x] API密钥安全存储 +- [x] 无本地数据存储 +- [x] GDPR合规性考虑 + +## 📋 Dify Marketplace 提交要求 + +### 必需文件 +1. **插件包** (`huoban-plugin-dify.zip`) - ✅ 已创建 +2. **插件清单** (`manifest.json`) - ✅ 已配置 +3. **OpenAPI规范** (`openapi.json`) - ✅ 已包含 +4. **README文档** (`README.md`) - ✅ 已完善 +5. **许可证文件** (`LICENSE`) - ✅ MIT许可证 +6. **隐私政策** (`PRIVACY.md`) - ✅ 已创建 + +### 技术要求 +1. **API规范**: OpenAPI 3.1.0 - ✅ 符合 +2. **认证类型**: API密钥 (Bearer token) - ✅ 已实现 +3. **多语言支持**: en_US, zh_Hans - ✅ 已支持 +4. **错误处理**: 完整的错误响应 - ✅ 已定义 +5. **版本管理**: 语义化版本控制 - ✅ 1.2.0 + +### 内容要求 +1. **清晰的插件描述** - ✅ 中英文描述 +2. **详细的使用说明** - ✅ 完整的文档 +3. **安装和配置指南** - ✅ 逐步说明 +4. **示例和用例** - ✅ 实际工作流示例 +5. **支持信息** - ✅ 多种支持渠道 + +## 🚀 发布准备状态 + +### 插件功能完整性 +- **核心功能**: 9个完整的API工具 +- **用户体验**: 逐步工作流设计 +- **错误处理**: 全面的错误反馈 +- **安全性**: API密钥加密传输 +- **性能**: 优化的API调用 + +### 文档完整性 +- **用户文档**: 完整的README +- **开发者文档**: OpenAPI规范 +- **合规文档**: 隐私政策 +- **支持文档**: 故障排除指南 + +### 市场适应性 +- **目标用户**: 企业用户、开发者、AI工程师 +- **使用场景**: CRM、项目管理、数据管理、自动化 +- **竞争优势**: 完整的伙伴云集成、AI自主探索能力 +- **定价策略**: 免费开源插件 + +## 📝 提交说明 + +### 提交到Dify Marketplace +1. 访问 Dify Marketplace 提交页面 +2. 上传 `huoban-plugin-dify.zip` 文件 +3. 填写插件信息（大部分信息已包含在manifest.json中） +4. 提供联系信息用于审核 +5. 提交审核 + +### 审核预期 +1. **技术审核**: 验证OpenAPI规范、认证配置 +2. **内容审核**: 检查文档完整性、隐私政策 +3. **功能审核**: 测试API功能、错误处理 +4. **安全审核**: 验证数据安全、合规性 + +### 发布后维护 +1. **版本更新**: 通过GitHub发布新版本 +2. **问题反馈**: 通过GitHub Issues收集反馈 +3. **用户支持**: 提供文档和社区支持 +4. **功能扩展**: 根据用户需求添加新功能 + +## 🔗 相关文件 +- `huoban-plugin-dify.zip` - 插件包 +- `manifest.json` - 插件清单 +- `README.md` - 用户文档 +- `PRIVACY.md` - 隐私政策 +- `openapi.json` - API规范 +- `LICENSE` - 许可证 + +--- + +**插件状态**: ✅ 准备提交到 Dify Marketplace + +**最后更新**: 2025年12月23日 +**版本**: 1.2.0 +**作者**: Zheng Xiao diff --git a/purexiao/huoban-api-suite/LICENSE b/purexiao/huoban-api-suite/LICENSE new file mode 100644 index 000000000..e5cbaeed9 --- /dev/null +++ b/purexiao/huoban-api-suite/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 purexiao + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/purexiao/huoban-api-suite/PRIVACY.md b/purexiao/huoban-api-suite/PRIVACY.md new file mode 100644 index 000000000..2e9e31a0a --- /dev/null +++ b/purexiao/huoban-api-suite/PRIVACY.md @@ -0,0 +1,113 @@ +# 伙伴云智能SDR插件隐私政策 + +**生效日期**：2025年12月23日 + +## 1. 数据收集声明 + +伙伴云智能SDR插件（以下简称"本插件"）**不直接收集、存储或处理任何用户个人数据**。本插件作为Dify平台与伙伴云API之间的桥梁，仅负责传输用户请求到伙伴云服务。 + +## 2. 数据传输说明 + +### 2.1 传输的数据类型 +当用户使用本插件时，以下数据可能通过本插件传输到伙伴云服务： + +- **API密钥**：用于身份验证的Bearer Token +- **查询参数**：用户在工作流程中输入的搜索条件、筛选参数等 +- **操作指令**：创建、读取、更新、删除数据的请求内容 +- **业务数据**：工作区、表格、记录等业务相关信息 + +### 2.2 数据流向 +``` +用户输入 → Dify平台 → 本插件 → 伙伴云API → 返回结果 +``` + +所有数据传输都通过HTTPS加密通道进行。 + +## 3. 第三方服务数据收集 + +本插件集成的**伙伴云服务**可能会收集和处理数据。用户应参考伙伴云的隐私政策： + +- [伙伴云隐私政策](https://www.huoban.com/privacy) + +根据伙伴云隐私政策，他们可能收集以下类型的数据： + +### 3.1 直接标识符（如适用） +- 姓名 +- 电子邮件地址 +- 电话号码 +- 公司信息 + +### 3.2 间接标识符（如适用） +- IP地址 +- 设备信息 +- 使用日志 +- 操作时间戳 + +### 3.3 业务数据 +- 工作区信息 +- 表格结构 +- 数据记录 +- 操作历史 + +## 4. 数据使用目的 + +通过本插件传输的数据仅用于： + +1. **身份验证**：验证用户对伙伴云服务的访问权限 +2. **API调用**：执行用户请求的操作（查询、创建、更新、删除） +3. **结果返回**：将操作结果返回给Dify平台和用户 + +## 5. 数据存储 + +本插件**不存储任何用户数据**。所有数据： +- 仅在传输过程中临时存在 +- 操作完成后立即释放 +- 不在本地或服务器持久化存储 + +## 6. 数据共享 + +本插件**不与任何第三方共享数据**，除了： +- 必要的API调用传输到伙伴云服务 +- Dify平台用于显示结果 + +## 7. 用户控制 + +用户可以通过以下方式控制数据： + +1. **API密钥管理**：用户可以随时在伙伴云平台更新或撤销API密钥 +2. **操作日志**：用户可以在伙伴云平台查看操作历史 +3. **数据删除**：用户可以直接在伙伴云平台删除业务数据 + +## 8. 安全措施 + +本插件实施以下安全措施： + +1. **加密传输**：所有API调用都使用HTTPS加密 +2. **无本地存储**：不在插件中存储敏感信息 +3. **最小权限**：仅请求执行操作所需的最小数据 + +## 9. 儿童隐私 + +本插件不面向13岁以下儿童设计，也不故意收集儿童个人信息。 + +## 10. 隐私政策更新 + +本隐私政策可能会不时更新。重大变更将在插件更新时通知用户。 + +## 11. 联系方式 + +如有关于本隐私政策的问题，请联系： + +- **插件开发者**：Zheng Xiao +- **支持渠道**：[GitHub Issues](https://github.com/your-repo/huoban-plugin-dify/issues) +- **伙伴云支持**：[support@huoban.com](mailto:support@huoban.com) + +## 12. 法律遵从 + +本插件遵守适用的数据保护法律和法规，包括但不限于： +- 中华人民共和国个人信息保护法 +- 通用数据保护条例（GDPR，如适用） + +--- + +**重要提示**：本插件仅作为工具使用，用户应对通过本插件传输的数据负责。建议用户定期审查伙伴云的隐私政策和服务条款。 diff --git a/purexiao/huoban-api-suite/README.md b/purexiao/huoban-api-suite/README.md new file mode 100644 index 000000000..3c2473f46 --- /dev/null +++ b/purexiao/huoban-api-suite/README.md @@ -0,0 +1,63 @@ +# Huoban API Suite - Dify Plugin + +[![Dify Plugin](https://img.shields.io/badge/Dify-Plugin-blue)](https://dify.ai) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Version](https://img.shields.io/badge/version-1.2.0-green)](https://github.com/purexiao/huoban-plugin-dify) + +A comprehensive Huoban API plugin for Dify AI platform that provides full CRUD operations, workspace management, and data automation capabilities. This plugin enables Dify AI agents to interact with Huoban (伙伴云) platform for intelligent business automation. + +## 🚀 Features + +### Workspace & Data Management +- **Workspace Discovery**: List all accessible workspaces (spaces) +- **Table Exploration**: Explore tables within workspaces with detailed field configurations +- **Intelligent Data Operations**: Create, read, update, and delete records in Huoban tables +- **Advanced Querying**: Complex filtering with AND/OR logical operations +- **Member Management**: Retrieve workspace member information for user assignments + +### AI-Powered Automation +- **Autonomous Exploration**: Step-by-step workflow for AI agents to discover data structures +- **Smart Field Mapping**: Automatic field ID detection and validation + +## 📦 Installation + +### Dify Marketplace Installation (Recommended) +1. Navigate to **Dify Marketplace** in your Dify instance +2. Search for **"Huoban API Suite"** +3. Click **"Install"** and follow the setup wizard +4. Configure authentication with your Huoban API key + +## 🔐 Authentication Configuration + +This plugin uses secure API key authentication: + +1. **Obtain API Key**: Get your API key from [Huoban Platform](https://www.huoban.com) +2. **Configure in Dify**: When adding the plugin, enter your API key in the format: + +``` +Bearer {YOUR_API_KEY} +``` + +## 🛠️ Available Tools + +1. **get_workspace_list**: Lists all workspaces accessible to the current user. +2. **get_table_list**: Retrieves all tables within a specified workspace. +3. **get_table_config**: Gets detailed field configuration for a specific table. **Critical for field mapping.** +4. **create_record**: Creates a new record in the specified table. +5. **query_table_data**: Queries table data with complex filtering conditions. +6. **get_item_detail**: Gets complete details of a specific record. +7. **update_record**: Updates an existing record. +8. **delete_record**: Deletes a specific record. +9. **get_space_members**: Retrieves member information within a workspace. + +## ⚠️ Error Handling & Troubleshooting + +| Error Type | Solution | +|------------|----------| +| Authentication Error | Regenerate API key in Huoban platform | +| Permission Denied | Check user permissions in Huoban | +| Invalid Field ID | Call `get_table_config` to get correct IDs | + +## 📄 License + +This plugin is licensed under the **MIT License**. \ No newline at end of file diff --git a/purexiao/huoban-api-suite/manifest.yaml b/purexiao/huoban-api-suite/manifest.yaml new file mode 100644 index 000000000..05a719092 --- /dev/null +++ b/purexiao/huoban-api-suite/manifest.yaml @@ -0,0 +1,56 @@ +schema_version: "1.0" +type: tool +namespace: huoban +name: + en_US: "Huoban API Suite" + zh_Hans: "伙伴云全能工具箱" +description: + en_US: "Comprehensive Huoban API toolkit for Dify AI platform. Enables AI agents to autonomously explore data structures, perform CRUD operations, and manage workspace members in Huoban." + zh_Hans: "Dify AI平台的伙伴云全能工具箱。使AI智能体能够自主探索数据结构、执行增删改查操作、并管理伙伴云工作区成员。" +icon: "🕵️" +icon_background: "#FEF7C3" +author: "purexiao" +author_url: "https://github.com/purexiao" +version: "1.2.0" +tags: + - crm + - api + - huoban + - data-management + - automation + - ai + - business-intelligence +categories: + - productivity + - business + - data + - ai-agents +homepage: "https://www.huoban.com" +repository: "https://github.com/purexiao/huoban-plugin-dify" +license: "MIT" +apis: + openapi: "./openapi.json" +authentication: + type: api_key + placement: header + name: "Open-Authorization" + description: + en_US: "Enter: Bearer {API_KEY} (Get API key from Huoban platform)" + zh_Hans: "请输入: Bearer {API_KEY} (从伙伴云平台获取API密钥)" +privacy_policy: "https://www.huoban.com/privacy" +support: "https://support.huoban.com" +release_notes: + "1.2.0": "Added comprehensive API suite with workspace management, table operations, and data CRUD capabilities" + "1.1.0": "Basic CRUD operations and API key authentication" + "1.0.0": "Initial release with workspace and table discovery" +data_collection: + description: + en_US: "This plugin transmits API keys and query parameters to Huoban API to perform requested operations. No data is permanently stored by the plugin itself." + zh_Hans: "此插件将API密钥和查询参数传输到伙伴云API以执行请求的操作。插件本身不永久存储任何数据。" + data_types: + - api_credentials + - query_parameters + - business_data + storage_duration: "transient" + data_sharing: + - huoban_api_only diff --git a/purexiao/huoban-api-suite/openapi.json b/purexiao/huoban-api-suite/openapi.json new file mode 100644 index 000000000..b8987d082 --- /dev/null +++ b/purexiao/huoban-api-suite/openapi.json @@ -0,0 +1,575 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Huoban API (Full Suite)", + "description": "伙伴云全能工具箱。包含自主探索数据结构、增删改查数据、以及获取成员列表的能力。", + "version": "v1.2.0" + }, + "servers": [ + { + "url": "https://api.huoban.com" + } + ], + "security": [ + { + "HuobanAuth": [] + } + ], + "paths": { + "/openapi/v1/space/list": { + "get": { + "operationId": "get_workspace_list", + "summary": "Step 1: 获取工作区列表", + "description": "获取当前用户可访问的所有工作区(Space)。当不知道 table 属于哪个空间时调用此接口作为第一步。", + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "spaces": { + "type": "array", + "items": { + "type": "object", + "properties": { + "space_id": { + "type": "string" + }, + "name": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + }, + "/openapi/v1/table/list": { + "post": { + "operationId": "get_table_list", + "summary": "Step 2: 获取表格列表", + "description": "根据工作区ID (space_id) 获取该工作区下所有的表格信息。用于查找目标表格的 table_id。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "space_id": { + "type": "integer", + "description": "工作区ID", + "example": 4000000000000001 + } + }, + "required": [ + "space_id" + ] + } + } + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "tables": { + "type": "array", + "items": { + "type": "object", + "properties": { + "table_id": { + "type": "integer" + }, + "name": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + }, + "/openapi/v1/table/{table_id}": { + "get": { + "operationId": "get_table_config", + "summary": "Step 3: 获取表格详细配置", + "description": "⚠️核心接口：根据表格ID直接获取字段配置。在「写入数据」、「修改数据」或「查询筛选」前，必须先调用此接口以获取准确的 field_id 映射关系。", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "description": "表格ID", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "table": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "fields": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "field_type": { + "type": "string" + }, + "required": { + "type": "boolean" + } + } + } + } + } + } + } + } + } + } + } + } + } + } + } + }, + "/openapi/v1/item": { + "post": { + "operationId": "create_record", + "summary": "Step 4: 创建数据(写入)", + "description": "向指定的表格中录入一条新数据。必须在获取表格配置后调用。fields 中的 Key 必须是 field_id。", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "table_id", + "fields" + ], + "properties": { + "table_id": { + "type": "string", + "description": "目标表格的 ID" + }, + "fields": { + "type": "object", + "description": "业务数据对象。Key 必须是 field_id。示例：{'2001': '张三', '2002': ['101']}。注意：选项/关联字段必须传 ID 数组。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "成功创建", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "item_id": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/openapi/v1/item/list": { + "post": { + "operationId": "query_table_data", + "summary": "Step 5: 查询数据列表 (含筛选)", + "description": "根据复杂条件筛选表格数据。⚠️ 调用前必须先调用 `get_table_config` 获取字段ID。支持 `and`/`or` 逻辑嵌套。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "table_id" + ], + "properties": { + "table_id": { + "type": "string", + "description": "目标表格ID" + }, + "limit": { + "type": "integer", + "default": 20, + "maximum": 100 + }, + "offset": { + "type": "integer", + "default": 0 + }, + "filter": { + "type": "object", + "description": "筛选对象。示例：{'and': [{'field': 'field_id', 'query': {'eq': 'value'}}]}", + "properties": { + "and": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FilterCondition" + } + }, + "or": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FilterCondition" + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "查询成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "total": { + "type": "integer" + }, + "items": { + "type": "array", + "items": { + "type": "object", + "description": "数据行" + } + } + } + } + } + } + } + } + } + } + } + }, + "/openapi/v1/item/{item_id}": { + "post": { + "operationId": "get_item_detail", + "summary": "Step 6: 获取单条数据详情", + "description": "根据 item_id 获取某一条数据的完整详情。通常用于确认数据内容。", + "parameters": [ + { + "name": "item_id", + "in": "path", + "required": true, + "description": "数据行ID", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "item": { + "type": "object", + "description": "数据详情对象", + "properties": { + "title": { + "type": "string" + }, + "fields": { + "type": "object", + "description": "所有字段的值，Key为 field_id" + } + } + } + } + } + } + } + } + } + } + } + }, + "put": { + "operationId": "update_record", + "summary": "Step 7: 修改/更新数据", + "description": "修改表格中已存在的一条数据。⚠️ 必须提供 item_id。Fields 中的 Key 必须是 field_id（通过 Step 3 获取）。", + "parameters": [ + { + "name": "item_id", + "in": "path", + "required": true, + "description": "需要修改的数据行ID", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "fields" + ], + "properties": { + "fields": { + "type": "object", + "description": "需要更新的字段键值对。Key 是 field_id。示例：{'2001': '新状态'}。注意：关联/选项字段通常需要传 ID 数组。", + "example": { + "2200000137788628": "新的文本内容", + "2200000137788650": [ + "1" + ] + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "更新成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "message": { + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "operationId": "delete_record", + "summary": "Step 8: 删除数据", + "description": "删除指定的一条数据。⚠️ 这是一个危险操作。", + "parameters": [ + { + "name": "item_id", + "in": "path", + "required": true, + "description": "要删除的数据行ID", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "删除成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "message": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/openapi/v1/space/member/list": { + "post": { + "operationId": "get_space_members", + "summary": "Step 9: 获取工作区成员列表", + "description": "获取工作区内的成员信息（User ID）。⚠️ 当需要填写“人员”类型的字段时，必须先调用此接口，用名字搜索并获取对应的 user_id。", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "space_id" + ], + "properties": { + "space_id": { + "type": "string", + "description": "工作区ID (Space ID)" + }, + "username": { + "type": "string", + "description": "搜索关键词（人名）" + }, + "limit": { + "type": "integer", + "default": 20 + }, + "offset": { + "type": "integer", + "default": 0 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "成功", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "users": { + "type": "array", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "HuobanAuth": { + "type": "apiKey", + "in": "header", + "name": "Open-Authorization", + "description": "请输入: Bearer {API_KEY}" + } + }, + "schemas": { + "FilterCondition": { + "type": "object", + "required": [ + "field", + "query" + ], + "properties": { + "field": { + "type": "string", + "description": "字段ID (field_id)" + }, + "query": { + "type": "object", + "description": "操作符对象", + "properties": { + "eq": { + "type": "string", + "description": "等于" + }, + "gt": { + "type": "number", + "description": "大于" + }, + "lt": { + "type": "number", + "description": "小于" + }, + "inc": { + "type": "array", + "items": { + "type": "integer" + }, + "description": "包含ID (选项/关联)" + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/purexiao/huoban-api-suite/package.json b/purexiao/huoban-api-suite/package.json new file mode 100644 index 000000000..b44f2be90 --- /dev/null +++ b/purexiao/huoban-api-suite/package.json @@ -0,0 +1,34 @@ +{ + "name": "huoban-plugin-dify", + "version": "1.2.0", + "description": "Comprehensive Huoban API plugin for Dify AI platform", + "main": "manifest.yaml", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "build": "echo \"Building plugin package...\"", + "package": "zip -r huoban-plugin-dify.zip . -x '*.git*' 'node_modules/*'" + }, + "keywords": [ + "dify", + "plugin", + "huoban", + "api", + "crm", + "automation" + ], + "author": "purexiao", + "license": "MIT", + "dependencies": {}, + "devDependencies": {}, + "repository": { + "type": "git", + "url": "https://github.com/purexiao/huoban-plugin-dify.git" + }, + "bugs": { + "url": "https://github.com/purexiao/huoban-plugin-dify/issues" + }, + "homepage": "https://github.com/purexiao/huoban-plugin-dify#readme", + "engines": { + "node": ">=16.0.0" + } +} \ No newline at end of file diff --git a/purexiao/huoban-api-suite/readme/README_zh_Hans.md b/purexiao/huoban-api-suite/readme/README_zh_Hans.md new file mode 100644 index 000000000..e9bb15bf0 --- /dev/null +++ b/purexiao/huoban-api-suite/readme/README_zh_Hans.md @@ -0,0 +1,37 @@ +# 伙伴云全能工具箱 (Huoban API Suite) + +[![Dify Plugin](https://img.shields.io/badge/Dify-Plugin-blue)](https://dify.ai) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +Dify AI平台的伙伴云全能工具箱。包含自主探索数据结构、增删改查数据、以及获取成员列表的能力。 + +## 🚀 功能特性 + +### 工作区与数据管理 +- **工作区发现**: 列出当前用户可访问的所有工作区 +- **表格探索**: 获取表格详细字段配置，帮助 AI 理解数据结构 +- **智能数据操作**: 支持增、删、改、查 (CRUD) 全套操作 +- **高级查询**: 支持 AND/OR 逻辑嵌套的复杂筛选 +- **成员管理**: 获取工作区成员列表，便于指派任务 + +## 📦 安装与配置 + +### 认证配置 +本插件使用 Bearer Token 认证： +1. 从 [伙伴云平台](https://www.huoban.com) 获取 API Key +2. 在 Dify 插件配置中输入：`Bearer {YOUR_API_KEY}` + +## 🛠️ 工具列表 + +1. **get_workspace_list (获取工作区列表)**: 第一步，获取所有可用的工作区。 +2. **get_table_list (获取表格列表)**: 获取指定工作区下的所有表格。 +3. **get_table_config (获取表格配置)**: **核心接口**，获取表格的字段 ID 映射关系，写入数据前必用。 +4. **create_record (创建记录)**: 向表格添加新数据。 +5. **query_table_data (查询表格数据)**: 支持复杂筛选条件的查询。 +6. **get_item_detail (获取记录详情)**: 获取单条数据的完整信息。 +7. **update_record (更新记录)**: 修改现有数据。 +8. **delete_record (删除记录)**: 删除数据。 +9. **get_space_members (获取空间成员)**: 获取成员 User ID，用于人员字段赋值。 + +## 📄 许可证 +本项目采用 MIT 许可证。 \ No newline at end of file