From 801d893cabb8b2e311e3f29c4247f19f2bef77f6 Mon Sep 17 00:00:00 2001 From: astrolabz Date: Fri, 29 Aug 2025 01:56:58 +0200 Subject: [PATCH 1/2] feat: Traduzione completa dei README.md in italiano MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Traduzione di 12 file README.md principali in italiano - Mantenimento del testo originale cinese sotto ogni traduzione - Aggiunta di emoji appropriati per migliorare la leggibilità - Preservazione completa del contenuto tecnico e dei blocchi di codice - File tradotti: * frontend/magic-flow/README.md * frontend/magic-web/README.md * backend/tiptap/README.md * backend/super-magic-module/README.md * frontend/upload-sdk/README.md * frontend/eslint-config/README.md * backend/async-event/README.md * backend/cloudfile/README.md * backend/code-executor/README.md * backend/easy-dingtalk/README.md * backend/flow-expr-engine/README.md * docs/README.md e sottodirectory - Miglioramento della documentazione per sviluppatori italiani --- CONTRIBUTING.md | 101 +++++++ README.md | 185 ++++++------- backend/async-event/README.md | 70 +++++ backend/cloudfile/README.md | 364 ++++++++++++++++++++++++- backend/code-executor/README.md | 265 ++++++++++++++++++ backend/easy-dingtalk/README.md | 88 ++++++ backend/flow-expr-engine/README.md | 44 +++ backend/super-magic-module/README.md | 179 +++++++++++++ backend/tiptap/README.md | 383 +++++++++++++++++++++++++++ docs/README.md | 25 ++ docs/en/index.md | 34 ++- docs/index.md | 44 +++ frontend/eslint-config/README.md | 100 +++++++ frontend/magic-flow/README.md | 85 ++++++ frontend/magic-web/README.md | 112 ++++++++ frontend/upload-sdk/README.md | 130 +++++++++ 16 files changed, 2115 insertions(+), 94 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8bfe91089..7a855a97d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,104 @@ +# CONTRIBUIRE 🎉 + +Stai cercando di contribuire a Magic — fantastico, non vediamo l'ora di vedere cosa farai. In quanto startup con risorse limitate, abbiamo grandi ambizioni per costruire le applicazioni LLM più potenti. Qualsiasi aiuto dalla community conta, davvero. + +Dobbiamo essere agili e rilasciare velocemente, ma vogliamo anche assicurare che i contributori come te abbiano un'esperienza il più possibile fluida. Abbiamo preparato questa guida alla contribuzione per questo scopo, per farti familiarizzare con il codice e con il modo in cui lavoriamo con i contributori, così potrai passare rapidamente alla parte divertente. + +Questa guida, come Magic stesso, è un lavoro in corso. Apprezziamo molto la tua comprensione se a volte è in ritardo rispetto al progetto reale, e accogliamo con favore qualsiasi feedback per migliorare. + +Per quanto riguarda la licenza, dedica un minuto a leggere la nostra breve [License and Contributor Agreement](./LICENSE). La community aderisce anche al [code of conduct](https://github.com/dtyq/.github/blob/main/CODE_OF_CONDUCT.md). 📜 + +## Prima di iniziare 🔎 + +Cerchi qualcosa da affrontare? Sfoglia le nostre [good first issues](https://github.com/dtyq/magic/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) e scegli una per iniziare! + +Hai una bella idea o una funzionalità da aggiungere? Apri una PR nel nostro [repository principale](https://github.com/dtyq/magic) e mostraci cosa hai costruito. + +Devi aggiornare una funzionalità esistente o risolvere dei bug? Apri una PR nel nostro [repository principale](https://github.com/dtyq/magic) e fai accadere la tua magia! ✨ + +Unisciti al divertimento, contribuisci e costruiamo qualcosa di straordinario insieme! 💡 + +Non dimenticare di collegare un issue esistente o aprirne uno nuovo nella descrizione della PR. + +### Segnalazione bug 🐛 + +> [! IMPORTANT] +> Assicurati di includere le seguenti informazioni quando invii una segnalazione di bug: + +- Un titolo chiaro e descrittivo +- Una descrizione dettagliata del bug, inclusi eventuali messaggi di errore +- Passi per riprodurre il bug +- Comportamento atteso +- **Log**, se disponibili; per problemi backend sono molto importanti, puoi trovarli nei docker-compose logs +- Screenshot o video, se applicabili 📷 + +Come priorizziamo: + +| Tipo di Issue | Priorità | +| --------------------------------------------------------------------------------------------- | --------------- | +| Bug in funzioni core (servizio cloud, impossibile fare il login, applicazioni non funzionanti, falle di sicurezza) | Critica | +| Bug non critici, miglioramenti di performance | Priorità Media | +| Correzioni minori (refusi, UI confusa ma funzionante) | Bassa Priorità | + +### Richieste di funzionalità ✨ + +> [! NOTE] +> Assicurati di includere le seguenti informazioni quando invii una richiesta di funzionalità: + +- Un titolo chiaro e descrittivo +- Una descrizione dettagliata della funzionalità +- Un caso d'uso per la funzionalità +- Qualsiasi altro contesto o screenshot relativo alla richiesta + +Come priorizziamo: + +| Tipo di Funzionalità | Priorità | +| --------------------------------------------------------------------------------------------- | --------------- | +| Funzionalità ad alta priorità etichettate da un membro del team | Alta Priorità | +| Richieste popolari dalla nostra [community feedback board](https://github.com/dtyq/magic/discussions/categories/feedbacks) | Priorità Media | +| Funzionalità non core e miglioramenti minori | Bassa Priorità | +| Valide ma non immediate | Futuro | + +## Inviare la tua PR 🔧 + +### Processo di Pull Request + +1. Fork del repository +2. Prima di creare una PR, crea un issue per discutere le modifiche che vuoi fare +3. Crea un nuovo branch per le tue modifiche +4. Aggiungi i test per le tue modifiche dove appropriato 🧪 +5. Assicurati che il tuo codice passi i test esistenti ✅ +6. Collega l'issue nella descrizione della PR, `fixes #` +7. Vieni mergiato! 🚀 + +### Configurare il progetto + +#### Frontend + +Per impostare il servizio frontend, fai riferimento alla nostra guida completa nel file `frontend/README.md`: https://github.com/dtyq/magic/blob/main/frontend/README.md. Questo documento fornisce istruzioni dettagliate per configurare correttamente l'ambiente frontend. + +#### Backend + +Per impostare il servizio backend, fai riferimento alle istruzioni nel file `backend/README.md`: https://github.com/dtyq/magic/blob/main/backend/README.md. Questo documento contiene indicazioni passo passo per avviare il backend senza problemi. + +#### Altre note importanti + +Ti consigliamo di leggere attentamente questo documento prima di procedere con la configurazione, poiché contiene informazioni essenziali su: +- Prerequisiti e dipendenze +- Passaggi di installazione +- Dettagli di configurazione +- Suggerimenti comuni per il troubleshooting + +Sentiti libero di contattarci se incontri problemi durante la configurazione. + +## Ottenere aiuto ❓ + +Se rimani bloccato o hai una domanda urgente mentre contribuisci, invia le tue richieste tramite l'issue GitHub correlato. + +--- + +Testo originale (inglese) — non cancellare, spostato sotto: + # CONTRIBUTING So you're looking to contribute to Magic - that's awesome, we can't wait to see what you do. As a startup with limited headcount and funding, we have grand ambitions to build most powerful LLM applications. Any help from the community counts, truly. diff --git a/README.md b/README.md index 7eec45687..831747601 100644 --- a/README.md +++ b/README.md @@ -1,201 +1,202 @@
- README in English - 简体中文版自述文件 + README in inglese + README in cinese semplificato
![Magic Open Source Product Matrix](https://public-cdn.letsmagic.ai/static/img/super-magic-publish-header-en.png?v=20250819) -# 🔥 Magic - First Open-Source All-in-One AI Productivity Platform +# 🔥 Magic - Prima piattaforma open source tutto-in-uno per la produttività AI 🚀

- Static Badge + Sito ufficiale - Stable Version + Versione stabile - Commits last month + Commit nell'ultimo mese - Issues closed + Issue chiuse - Discussion posts + Discussioni - Static Badge + Creato con Magic 🔮

-Magic aims to help enterprises of all sizes quickly build and deploy AI applications to achieve a 100x increase in productivity. +Magic mira ad aiutare imprese di tutte le dimensioni a costruire e distribuire rapidamente applicazioni AI per ottenere un aumento di produttività di 100x. ⚡️ -## Magic Product Matrix +## Matrice di prodotto Magic 🧩 -Magic is the first **"open-source all-in-one AI productivity platform"**, not a single AI product, but a comprehensive product matrix with rich capabilities. +Magic è la prima **"piattaforma open source tutto-in-uno per la produttività AI"**, non un singolo prodotto AI, ma una matrice di prodotti completa con capacità ricche. ![Product Matrix](https://public-cdn.letsmagic.ai/static/img/super-magic-open-source-projects-en.png?v=20250819) -- **[Super Magic](https://github.com/dtyq/super-magic)** - A **general-purpose AI Agent** designed for complex task scenarios -- **[Magic IM](https://github.com/dtyq/magic)** - An enterprise-grade instant messaging system that integrates AI Agent conversations with internal enterprise communication -- **[Magic Flow](https://github.com/dtyq/magic)** - A powerful visual AI workflow orchestration system -- **Teamshare OS** (Coming soon) - An enterprise-grade online collaborative office system +- **[Super Magic](https://github.com/dtyq/super-magic)** - Un **AI Agent general purpose** progettato per scenari di compiti complessi 🤖 +- **[Magic IM](https://github.com/dtyq/magic)** - Un sistema di messaggistica istantanea di livello enterprise che integra conversazioni con Agent AI nella comunicazione interna aziendale 💬 +- **[Magic Flow](https://github.com/dtyq/magic)** - Un potente sistema di orchestrazione di workflow AI visuale 🔁 +- **Teamshare OS** (Prossimamente) - Un sistema di ufficio collaborativo online di livello enterprise 🏢 -In addition to the above AI products, we have also open-sourced some of the infrastructure we used to build these products: +Oltre ai prodotti AI sopra, abbiamo anche open-sourcizzato alcune delle infrastrutture utilizzate per costruire questi prodotti: -- **[Agentlang](https://github.com/dtyq/agentlang)** - A language-first AI Agent Framework for building AI agents with natural language (currently available in Python version, TypeScript version coming soon) -- **[Magic Lens](https://github.com/dtyq/magiclens)** - A powerful and flexible HTML to Markdown conversion tool that uses an extensible rule system to accurately convert complex HTML documents to concise Markdown format -- **Magic Use** (Coming soon) - A revolutionary browser operation tool specifically designed for AI Agents -- **Magic Space** (Coming soon) - A new static content hosting management system specifically designed for AI Agents -- **Sandbox OS** (Coming soon) - A powerful sandbox system for AI Agent runtime +- **[Agentlang](https://github.com/dtyq/agentlang)** - Un framework per Agent AI basato sul linguaggio per costruire agenti AI con linguaggio naturale (attualmente disponibile in versione Python, versione TypeScript in arrivo) 🗣️ +- **[Magic Lens](https://github.com/dtyq/magiclens)** - Uno strumento potente e flessibile di conversione da HTML a Markdown che utilizza un sistema di regole estensibile per convertire accuratamente documenti HTML complessi in formato Markdown conciso 🔍 +- **Magic Use** (Prossimamente) - Uno strumento rivoluzionario per operazioni browser specificamente progettato per Agent AI 🧭 +- **Magic Space** (Prossimamente) - Un nuovo sistema di gestione di hosting contenuti statici specificamente progettato per Agent AI 🌐 +- **Sandbox OS** (Prossimamente) - Un potente sistema sandbox per il runtime degli Agent AI 🛡️ -### Super Magic +### Super Magic 🤖 -A powerful **general-purpose AI Agent** specially designed for complex task scenarios. Through a multi-agent design system and rich tool capabilities, Super Magic supports intelligent abilities such as **autonomous task understanding**, **autonomous task planning**, **autonomous action**, and **autonomous error correction**. It can understand natural language instructions, execute various business processes, and deliver final target results. As the flagship product of the Magic product matrix, Super Magic provides powerful secondary development capabilities through open source, allowing enterprises to quickly build and deploy intelligent assistants that meet specific business needs, greatly improving decision-making efficiency and quality. +Un potente **AI Agent general purpose** appositamente progettato per scenari di compiti complessi. Attraverso un sistema di design multi-agente e ricche capacità di tool, Super Magic supporta abilità intelligenti come **comprensione autonoma del compito**, **pianificazione autonoma del compito**, **azione autonoma** e **correzione autonoma degli errori**. Può comprendere istruzioni in linguaggio naturale, eseguire vari processi aziendali e fornire risultati finali. Come prodotto di punta della matrice Magic, Super Magic offre potenti capacità di sviluppo secondario tramite open source, permettendo alle imprese di costruire e distribuire rapidamente assistenti intelligenti che soddisfano esigenze aziendali specifiche, migliorando notevolmente l'efficienza e la qualità delle decisioni. ⚙️ ![Super Magic](https://public-cdn.letsmagic.ai/static/img/super-magic-buffett.gif) -#### Super Magic Case Studies -- [Analysis of Investment Insights from Buffett's 2025 Shareholders Meeting](https://www.letsmagic.cn/share/777665156986277889) -- [Analysis of Stocks Related to Beijing Humanoid Robot Half Marathon](https://www.letsmagic.cn/share/774280936479625217) -- [Summary of Key Points from 'Thinking, Fast and Slow](https://www.letsmagic.cn/share/777461325648195584) -- [Auntie Jenny IPO Analysis and Investment Recommendations](https://www.letsmagic.cn/share/777604044873928705) -- [SKU Sales Forecast Requirements](https://www.letsmagic.cn/share/771022574397648897) -- For more case studies, please visit the [Official Website](https://www.letsmagic.ai) +#### Casi di studio Super Magic 📚 +- [Analisi degli insight sugli investimenti dall'assemblea degli azionisti di Buffett 2025](https://www.letsmagic.cn/share/777665156986277889) 🔎 +- [Analisi delle azioni correlate alla mezza maratona dei robot umanoidi di Pechino](https://www.letsmagic.cn/share/774280936479625217) 🤖🏃 +- [Riepilogo dei punti chiave di 'Thinking, Fast and Slow'](https://www.letsmagic.cn/share/777461325648195584) 📘 +- [Analisi IPO di Auntie Jenny e raccomandazioni di investimento](https://www.letsmagic.cn/share/777604044873928705) 📈 +- [Requisiti di previsione vendite SKU](https://www.letsmagic.cn/share/771022574397648897) 🧾 +- Per altri casi di studio, visita il [Sito ufficiale](https://www.letsmagic.ai) 🌐 -### Magic Flow +### Magic Flow 🔁 -Magic Flow is a powerful visual AI workflow orchestration system that allows users to build complex AI Agent workflows on a free canvas. It has the following core features: +Magic Flow è un potente sistema di orchestrazione di workflow AI visuale che permette agli utenti di costruire complessi workflow di Agent AI su una canvas libera. Ha le seguenti caratteristiche principali: -- **Visual Orchestration**: Intuitive drag-and-drop interface allows designing complex AI workflows without coding, easily implementing various functional combinations through node connections. -- **Rich Component Library**: Built-in variety of preset components, including text processing, image generation, code execution modules, meeting diverse business needs. -- **Comprehensive Model Support**: Compatible with any large model following the OpenAI API protocol, flexibly choosing AI capabilities suitable for business scenarios. -- **System Integration Capability**: Seamless integration with Magic IM and other third-party IM systems (WeCom, DingTalk, Feishu), enabling cross-platform collaboration. -- **Custom Extensions**: Support for custom tool node development to meet specific business scenario requirements. -- **Real-time Debugging and Monitoring**: Providing comprehensive debugging and monitoring functions to help quickly identify and solve problems in workflows, ensuring stable operation of AI applications. +- Visual Orchestration: Interfaccia drag-and-drop intuitiva che consente di progettare workflow AI complessi senza codice, implementando facilmente varie combinazioni funzionali tramite connessioni tra nodi. 🖱️ +- Libreria di componenti ricca: Varie componenti preimpostate integrate, inclusi moduli di elaborazione testo, generazione immagini, esecuzione codice, per soddisfare diverse esigenze aziendali. 🧩 +- Supporto completo dei modelli: Compatibile con qualsiasi large model che segua il protocollo OpenAI API, consentendo di scegliere in modo flessibile le capacità AI adatte agli scenari aziendali. 🤝 +- Capacità di integrazione di sistema: Integrazione senza soluzione di continuità con Magic IM e altri sistemi IM di terze parti (WeCom, DingTalk, Feishu), abilitando la collaborazione cross-platform. 🔗 +- Estensioni personalizzate: Supporto per lo sviluppo di nodi tool personalizzati per soddisfare requisiti di scenari aziendali specifici. 🛠️ +- Debugging e monitoraggio in tempo reale: Funzioni complete di debugging e monitoraggio per aiutare a identificare e risolvere rapidamente problemi nei workflow, garantendo un funzionamento stabile delle applicazioni AI. 🐞📈 ![Magic Flow](https://public-cdn.letsmagic.ai/static/img/magic-flow.png) -As an important component of the Magic product matrix, Magic Flow can be seamlessly integrated with other Magic products to create a complete enterprise-level AI application ecosystem. +Come componente importante della matrice Magic, Magic Flow può essere integrato senza problemi con altri prodotti Magic per creare un ecosistema completo di applicazioni AI di livello enterprise. 🏗️ ![Magic Multi-Agents and Events](https://public-cdn.letsmagic.ai/static/img/super-magic-multi-agents-and-events-en.png?v=20250819) -### Magic IM +### Magic IM 💬 -Magic IM is an enterprise-grade AI Agent conversation system designed specifically for internal knowledge management and intelligent customer service scenarios. It provides rich conversational capabilities, supporting multi-turn dialogues, context understanding, knowledge base retrieval, and other functions, allowing enterprises to quickly build intelligent customer service, knowledge assistants, and other applications. +Magic IM è un sistema di conversazione con Agent AI di livello enterprise progettato specificamente per la gestione della conoscenza interna e scenari di assistenza clienti intelligente. Fornisce ricche capacità conversazionali, supportando dialoghi multi-turno, comprensione del contesto, recupero da knowledge base e altre funzioni, permettendo alle imprese di costruire rapidamente assistenza clienti intelligente, assistenti di conoscenza e altre applicazioni. -Magic IM has the following core features: +Magic IM ha le seguenti caratteristiche principali: -- **Knowledge Base Management**: Powerful knowledge base management functions, supporting import of various document formats, automatic indexing, and semantic retrieval, ensuring AI answers based on authentic enterprise knowledge. -- **Conversation Management**: Comprehensive conversation management, supporting topic distinction for different conversation content, enabling both AI Agent conversations and communication with people within the organization. -- **Group Chat Capability**: Powerful group chat functionality, supporting real-time collaborative discussions among multiple people, with AI intelligently participating in group chats and providing instant answers, promoting efficient team communication and knowledge sharing. -- **Multi-organizational Architecture**: Support for multi-organization deployment and strict organizational data isolation, with each organization having independent data space and access permissions. -- **Data Security**: Strict data isolation and access control mechanisms, multi-level permission management, safeguarding sensitive enterprise information and ensuring no data leakage between organizations. +- Gestione della knowledge base: Potenti funzioni di gestione della knowledge base, supportando l'importazione di vari formati di documento, indicizzazione automatica e retrieval semantico, assicurando risposte AI basate su conoscenza aziendale autentica. 📚 +- Gestione delle conversazioni: Gestione completa delle conversazioni, supportando la distinzione di argomenti per contenuti conversazionali diversi, abilitando sia conversazioni con Agent AI sia comunicazioni tra persone all'interno dell'organizzazione. 🧵 +- Capacità di chat di gruppo: Funzionalità di chat di gruppo avanzate, supportando discussioni collaborative in tempo reale tra più persone, con l'AI che partecipa in modo intelligente e fornisce risposte immediate, promuovendo comunicazione e condivisione della conoscenza efficaci. 👥 +- Architettura multi-organizzativa: Supporto per distribuzione multi-organizzazione e rigorosa isolazione dei dati organizzativi, con ogni organizzazione che dispone di spazio dati e permessi di accesso indipendenti. 🏢🔒 +- Sicurezza dei dati: Meccanismi di isolamento e controllo degli accessi rigorosi, gestione dei permessi multi-livello, proteggendo informazioni sensibili aziendali ed evitando perdite di dati tra organizzazioni. 🔐 ![Magic IM](https://public-cdn.letsmagic.ai/static/img/magic-im-group-chat-en.png?v=20250819) -## Teamshare OS +## Teamshare OS 🏢 -Teamshare OS is a modern enterprise-grade collaborative office platform designed to enhance team collaboration efficiency and knowledge management. As an important component of the Magic product matrix, Teamshare deeply integrates AI capabilities into daily office scenarios, achieving intelligent workflows and knowledge management. +Teamshare OS è una piattaforma di collaborazione aziendale moderna progettata per migliorare l'efficienza della collaborazione di team e la gestione della conoscenza. Come componente importante della matrice Magic, Teamshare integra profondamente le capacità AI nelle attività quotidiane d'ufficio, ottenendo workflow e gestione della conoscenza intelligenti. -Teamshare OS has the following core features: +Teamshare OS ha le seguenti caratteristiche principali: -- **Intelligent Document Management**: Support for online editing, collaboration, and version control of various document formats, AI-assisted content generation and optimization, making team document management more efficient. -- **Magic Table**: Powerful multi-dimensional data management tool, supporting custom field types, diverse views, and automated workflows, combined with AI capabilities to achieve intelligent data processing, meeting diverse data management needs. -- **Project Collaboration Management**: Intuitive project boards and task management, supporting custom workflows, combined with AI intelligent analysis to provide project progress forecasting and resource optimization suggestions. -- **Knowledge Base**: Powerful knowledge consolidation and retrieval system, automatically structuring internal enterprise documents to form sustainable accumulated enterprise knowledge assets. -- **Comprehensive Integration Capability**: Seamless integration with Magic product matrix, while supporting connection with mainstream office software and enterprise applications, creating a unified work platform. +- Gestione intelligente dei documenti: Supporto per editing online, collaborazione e controllo delle versioni di vari formati di documento, generazione e ottimizzazione dei contenuti assistita dall'AI, rendendo la gestione dei documenti di team più efficiente. 📝 +- Magic Table: Potente strumento di gestione dati multidimensionale, supportando tipi di campo personalizzati, viste multiple e workflow automatizzati, combinato con capacità AI per ottenere elaborazione dati intelligente, soddisfacendo esigenze diverse di gestione dei dati. 📊 +- Gestione collaborazione progetti: Bacheche progetto e gestione attività intuitive, supportando workflow personalizzati, combinate con analisi intelligente AI per fornire previsioni sul progresso del progetto e suggerimenti di ottimizzazione delle risorse. ✅ +- Knowledge Base: Potente sistema di consolidamento e ricerca della conoscenza, strutturando automaticamente i documenti interni dell'azienda per formare asset di conoscenza aziendale sostenibili. 🧠 +- Capacità di integrazione completa: Integrazione senza soluzione di continuità con la matrice di prodotti Magic, supportando anche il collegamento con software d'ufficio e applicazioni aziendali principali, creando una piattaforma di lavoro unificata. 🔗 -### Magic Table +### Magic Table 🧾 https://gist.github.com/user-attachments/assets/6ef46e66-292c-4a8a-8a00-a3b9fb7beec7 -### Magic Doc +### Magic Doc 📄 https://gist.github.com/user-attachments/assets/7327f331-be7d-4aeb-8e19-0949adde66b2 -## 🚀 Using Super Magic +## 🚀 Uso di Super Magic -### Cloud Service +### Servizio Cloud ☁️ -We provide [cloud services](https://www.letsmagic.ai) for [Super Magic](https://www.letsmagic.ai), [Magic IM](https://www.letsmagic.ai), and [Magic Flow](https://www.letsmagic.ai), allowing anyone to start trying and using them with zero setup, providing all features of the open-source version. -*Currently, an invitation code is required for access, which can be applied for online and granted for trial use after approval.* +Forniamo [servizi cloud](https://www.letsmagic.ai) per [Super Magic](https://www.letsmagic.ai), [Magic IM](https://www.letsmagic.ai) e [Magic Flow](https://www.letsmagic.ai), permettendo a chiunque di iniziare a provarli e usarli senza configurazione, offrendo tutte le funzionalità della versione open source. +*Attualmente è richiesto un codice di invito per l'accesso, che può essere richiesto online e concesso per uso di prova dopo approvazione.* 🔑 -### Magic for Enterprises/Organizations +### Magic per imprese/organizzazioni 🏢✨ -We provide more powerful management capabilities and features for teams and enterprises. [Send us an email](mailto:bd@dtyq.com?subject=[GitHub]Business%20License%20Inquiry) to discuss enterprise needs. +Forniamo capacità e funzionalità di gestione più potenti per team e imprese. [Mandaci una email](mailto:bd@dtyq.com?subject=[GitHub]Business%20License%20Inquiry) per discutere le esigenze enterprise. -### Self-hosted Community Edition +### Edizione Community self-hosted 🧑‍💻 -#### System Requirements -- Docker 24.0+ +#### Requisiti di sistema ⚙️ +- Docker 24.0+ 🐳 - Docker Compose 2.0+ -#### Start the System Using Docker +#### Avviare il sistema con Docker ▶️ ```bash -# Clone repository +# Clona il repository git clone https://github.com/dtyq/magic.git cd magic -# Start service in foreground +# Avvia il servizio in primo piano ./bin/magic.sh start ``` -##### Other Commands +##### Altri comandi 🛠️ ```bash -# Start service in background +# Avvia il servizio in background ./bin/magic.sh daemon -# Check service status +# Controlla lo stato del servizio ./bin/magic.sh status -# View logs +# Visualizza i log ./bin/magic.sh logs ``` -##### Configure Environment Variables +##### Configurare le variabili d'ambiente 🔧 ```bash -# Configure Magic environment variables, must configure at least one large language model's environment variables to use Magic normally +# Configura le variabili d'ambiente di Magic, è necessario configurare almeno le variabili d'ambiente di un modello linguistico grande per usare normalmente Magic cp .env.example .env -# Configure Super Magic environment variables, must configure any large language model that supports OpenAI format to use it normally +# Configura le variabili d'ambiente di Super Magic, è necessario configurare qualsiasi modello che supporti il formato OpenAI per usarlo normalmente ./bin/magic.sh status cp config/.env_super_magic.example .env_super_magic ``` -##### Access Services -- API Service: http://localhost:9501 -- Web Application: http://localhost:8080 +##### Accesso ai servizi 🔐 +- Servizio API: http://localhost:9501 +- Applicazione Web: http://localhost:8080 - Account `13812345678`：Password `letsmagic.ai` - Account `13912345678`：Password `letsmagic.ai` -- RabbitMQ Management Interface: http://localhost:15672 +- Interfaccia di gestione RabbitMQ: http://localhost:15672 - Username: admin - Password: magic123456 -Official Website: [https://www.letsmagic.ai](https://www.letsmagic.ai) -Documentation: [https://docs.letsmagic.cn/en](https://docs.letsmagic.cn/en) +Sito ufficiale: [https://www.letsmagic.ai](https://www.letsmagic.ai) 🌐 +Documentazione: [https://docs.letsmagic.cn/en](https://docs.letsmagic.cn/en) 📚 -## Contribution +## Contributi 🙌 -For those who want to contribute code, please refer to our [Contribution Guide](https://github.com/dtyq/magic/blob/master/CONTRIBUTING.md). -Also, please consider supporting Magic through social media, events, and conferences. The development of Magic relies on your support. +Per chi desidera contribuire con codice, fare riferimento alla nostra [Guida ai contributi](https://github.com/dtyq/magic/blob/master/CONTRIBUTING.md). +Inoltre, considera di supportare Magic tramite social media, eventi e conferenze. Lo sviluppo di Magic si basa sul tuo supporto. ❤️ -## Security Vulnerabilities +## Vulnerabilità di sicurezza 🔒 -If you discover a security vulnerability in Magic, please send an email to the Magic official team at [team@dtyq.com](mailto:team@dtyq.com). All security vulnerabilities will be promptly addressed. +Se scopri una vulnerabilità di sicurezza in Magic, invia un'email al team ufficiale Magic a [team@dtyq.com](mailto:team@dtyq.com). Tutte le vulnerabilità di sicurezza saranno affrontate tempestivamente. -## 📄 License +## 📄 Licenza -This repository follows the [Magic Open Source License](LICENSE), which is essentially Apache 2.0 but with some additional restrictions. +Questo repository segue la [Magic Open Source License](LICENSE), che è essenzialmente Apache 2.0 ma con alcune restrizioni aggiuntive. -## 🙏 Acknowledgements +## 🙏 Ringraziamenti -Thanks to all developers who have contributed to Magic! +Grazie a tutti gli sviluppatori che hanno contribuito a Magic! 🎉 [![Star History Chart](https://api.star-history.com/svg?repos=dtyq/magic&type=Date)](https://star-history.com/#dtyq/magic&Date) + diff --git a/backend/async-event/README.md b/backend/async-event/README.md index bea6f287b..92fa11ce9 100644 --- a/backend/async-event/README.md +++ b/backend/async-event/README.md @@ -1,3 +1,73 @@ +# Eventi Asincroni ⏰ + +- Gli eventi verranno inseriti in una coroutine, poi eseguiti in ordine +- Il codice core è `\Dtyq\AsyncEvent\AsyncEventDispatcher::dispatch` + +## 📦 Installazione +- Installazione +``` +composer require dtyq/async-event +``` +- Pubblicare configurazione +``` +php bin/hyperf.php vendor:publish dtyq/async-event +``` +- Eseguire migrazione database +``` +php bin/hyperf.php migrate +``` + +## 🚀 Modalità d'Uso + +- Per non influenzare la logica esistente, utilizzare il nuovo dispatcher + +demo +```php +request->input('user', 'Hyperf'); + $method = $this->request->getMethod(); + + $this->asyncEventDispatcher->dispatch(new DemoEvent([123,222], 9)); + + return [ + 'method' => $method, + 'message' => "Hello {$user}.", + ]; + } +} + +``` + +- Raggiunto il numero massimo di esecuzioni, è possibile effettuare notifiche di messaggio, ma è necessario aggiungere la configurazione personalmente, questo progetto fornisce solo l'evento di raggiungimento del massimo tentativo di retry + + +## ⚠️ Note Importanti + +- Negli eventi cercare di non utilizzare il contesto della coroutine per passare dati, perché gli eventi sono asincroni, potrebbero causare inconsistenza dei dati + +--- + # 异步事件 - 事件将会放到一个协程中，然后按照顺序执行 diff --git a/backend/cloudfile/README.md b/backend/cloudfile/README.md index 407c5d303..93f9de64e 100644 --- a/backend/cloudfile/README.md +++ b/backend/cloudfile/README.md @@ -1,7 +1,367 @@ -

cloud-file

+

cloud-file ☁️

.

+## 📖 Introduzione + +Questo SDK è una versione avanzata dell'SDK per servizi file, fornisce più funzionalità e maggiore facilità d'uso. + +Include chiamate semplificate integrate per Aliyun, Volcano Engine e servizi file, completando operazioni come upload, download, cancellazione file con poche righe di codice. + +Supporta modalità di upload diretto backend, ottenendo credenziali temporanee per upload diretto dei file al cloud storage dal backend, riducendo il carico del server. + +Configurazione `FilesystemAdapter` sostituibile, personalizzazione più potente. + +Estrae funzionalità comuni del servizio file nel pacchetto, utilizzabile senza dipendere dal servizio file. + +## 🌐 Cloud Supportati + + - Servizio file proxy per Aliyun, Volcano Engine + - Aliyun + - Volcano Engine + +## ⚡ Funzionalità Importanti +- [x] Ottieni credenziali temporanee +- [x] Carica file - tramite upload diretto con credenziali temporanee +- [x] Copia file +- [x] Cancella file +- [x] Ottieni link accessibili in batch +- [x] Ottieni metadati file + +## ⚠️ Note Importanti +Se vuoi utilizzare Aliyun o Volcano Engine diretti, devi prima installare i FilesystemAdapter corrispondenti, come + +```composer +"suggest": { + "hyperf/logger": "Required to use the Hyperf.", + "hyperf/di": "Required to use the Hyperf.", + "hyperf/config": "Required to use the Hyperf.", + "hyperf/cache": "Required to use the Hyperf.", + "alibabacloud/sts": "^1.8", + "aliyuncs/oss-sdk-php": "^2.7", + "league/flysystem": "^2.0", + "xxtime/flysystem-aliyun-oss": "^1.6", + "volcengine/ve-tos-php-sdk": "^2.1", + "volcengine/volc-sdk-php": "^1.0" +}, +``` + +Oppure nella configurazione config, aggiungere il parametro driver, cioè FilesystemAdapter, a causa di problemi di compatibilità delle dipendenze tra pacchetti, potrebbero esserci bug, ma attualmente l'opportunità di utilizzare il servizio file è maggiore, per ora ignoriamo questo, se ci sono problemi li sistemeremo + +## 📦 Installazione + +```shell +$ composer require dtyq/cloudfile -vvv +``` + +## ⚙️ Configurazione + +```php +$configs = [ + 'storages' => [ + // Esempio configurazione servizio file + 'file_service_test' => [ + 'adapter' => 'file_service', + 'config' => [ + // Indirizzo servizio file + 'host' => 'xxx', + // Platform servizio file + 'platform' => 'xxx', + // Key servizio file + 'key' => 'xxx', + ], + ], + // Esempio configurazione Aliyun + 'aliyun_test' => [ + 'adapter' => 'aliyun', + 'config' => [ + 'accessId' => 'xxx', + 'accessSecret' => 'xxx', + 'bucket' => 'xxx', + 'endpoint' => 'xxx', + 'role_arn' => 'xxx', + ], + ], + // Esempio configurazione Volcano Engine + 'tos_test' => [ + 'adapter' => 'tos', + 'config' => [ + 'region' => 'xxx', + 'endpoint' => 'xxx', + 'ak' => 'xxx', + 'sk' => 'xxx', + 'bucket' => 'xxx', + 'trn' => 'xxx', + ], + ], + ], +]; + +$container = new SdkContainer([ + // Configurazione base SDK + 'sdk_name' => 'easy_file_sdk', + 'exception_class' => CloudFileException::class,· + // Configurazione cloudfile + 'cloudfile' => $configs, +]); + +$cloudFile = new CloudFile($container); +``` + +## 🔧 Caratteristiche Speciali Servizio File +Poiché è necessario richiedere il servizio file, richiede token dinamico e organization-code, qui deve essere messo nel parametro options, **tutte** le richieste del servizio file devono includerlo, come segue + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', + 'cache' => false, // Impostare secondo necessità, suggerito false per debug facile +]; + +``` + +## 🚀 Uso + +### Ottieni Credenziali Temporanee + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$credentialPolicy = new CredentialPolicy([ + 'sts' => false, + 'roleSessionName' => 'test', +]); +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$data = $filesystem->getUploadTemporaryCredential($credentialPolicy, $options); +``` + +### 上传文件 - 通过临时凭证直传 +上传完成后，记得查看`$uploadFile->getKey()`，来获取上传后的文件实际路径（因为文件服务会拼接 组织/应用 前缀） + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$credentialPolicy = new CredentialPolicy([ + 'sts' => false, +]); + +$realPath = __DIR__ . '/../test.txt'; + +$uploadFile = new UploadFile($realPath, 'easy-file'); +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$filesystem->uploadByCredential($uploadFile, $credentialPolicy, $options); +``` + +### 复制文件 + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +// 复制文件成功后，要获取这个 path 结果才是真实地址，因为文件服务会有权限处理 +$path = $filesystem->duplicate('easy-file/test.txt', 'easy-file/test-copy.txt', $options); +``` + +### 删除文件 + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$filesystem->destroy('easy-file/test.txt', $options); +``` + +### 批量获取可访问链接 +> 请求文件服务时，不检测是否存在，直接返回链接 +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$list = $filesystem->getLinks([ + 'easy-file/file-service.txt', + 'easy-file/test.txt', +], [], 7200, $options); +``` + +### 获取文件元数据 + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$list = $filesystem->getMetas([ + 'easy-file/file-service.txt', + 'easy-file/test.txt'], $options); +``` +## Hyperf 快捷使用 + +### 发布配置文件 +```shell +$ php bin/hyperf.php vendor:publish dtyq/cloudfile +``` + +### 使用 +```php +// 这里可以在构造中注入 CloudFileFactory +$cloudFile = \Hyperf\Support\make(CloudFileFactory::class)->create(); + +$filesystem = $cloudFile->get('file_service'); + +$options = [ + // 这里的动态 token 需要自行传入 + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$list = $filesystem->getLinks([ + 'easy-file/file-service.txt', + 'easy-file/test.txt', +], [], 7200, $options); + +$link = $list[0]->getUrl(); +``` + +### Ottieni Credenziali Temporanee + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$credentialPolicy = new CredentialPolicy([ + 'sts' => false, + 'roleSessionName' => 'test', +]); +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$data = $filesystem->getUploadTemporaryCredential($credentialPolicy, $options); +``` + +### Carica File - Tramite Upload Diretto con Credenziali Temporanee +Dopo il completamento dell'upload, ricordati di controllare `$uploadFile->getKey()` per ottenere il percorso file effettivo dopo l'upload (perché il servizio file concatenerà il prefisso organizzazione/applicazione) + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$credentialPolicy = new CredentialPolicy([ + 'sts' => false, + 'roleSessionName' => 'test', +]); + +$realPath = __DIR__ . '/../test.txt'; + +$uploadFile = new UploadFile($realPath, 'easy-file'); +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$filesystem->uploadByCredential($uploadFile, $credentialPolicy, $options); +``` + +### Copia File + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +// Dopo la copia riuscita del file, ottenere questo risultato path è l'indirizzo reale, perché il servizio file avrà elaborazione permessi +$path = $filesystem->duplicate('easy-file/test.txt', 'easy-file/test-copy.txt', $options); +``` + +### Cancella File + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$filesystem->destroy('easy-file/test.txt', $options); +``` + +### Ottieni Link Accessibili in Batch +> Quando richiedi il servizio file, non verifica l'esistenza, restituisce direttamente il link +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$list = $filesystem->getLinks([ + 'easy-file/file-service.txt', + 'easy-file/test.txt', +], [], 7200, $options); +``` + +### Ottieni Metadati File + +```php +$filesystem = $cloudFile->get('file_service_test'); + +$options = [ + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$list = $filesystem->getMetas([ + 'easy-file/file-service.txt', + 'easy-file/test.txt'], $options); +``` + +## ⚡ Uso Rapido Hyperf + +### Pubblica File di Configurazione +```shell +$ php bin/hyperf.php vendor:publish dtyq/cloudfile +``` + +### Uso +```php +// Qui puoi iniettare CloudFileFactory nel costruttore +$cloudFile = \Hyperf\Support\make(CloudFileFactory::class)->create(); + +$filesystem = $cloudFile->get('file_service'); + +$options = [ + // Il token dinamico qui deve essere passato autonomamente + 'token' => 'xxx', + 'organization-code' => 'xxx', +]; +$list = $filesystem->getLinks([ + 'easy-file/file-service.txt', + 'easy-file/test.txt', +], [], 7200, $options); + +$link = $list[0]->getUrl(); +``` + +--- + +# cloud-file + ## 介绍 本 sdk 为文件服务 sdk 增强版，提供了更多的功能，更加易用。 @@ -148,6 +508,7 @@ $filesystem = $cloudFile->get('file_service_test'); $credentialPolicy = new CredentialPolicy([ 'sts' => false, + 'roleSessionName' => 'test', ]); $realPath = __DIR__ . '/../test.txt'; @@ -213,6 +574,7 @@ $list = $filesystem->getMetas([ 'easy-file/file-service.txt', 'easy-file/test.txt'], $options); ``` + ## Hyperf 快捷使用 ### 发布配置文件 diff --git a/backend/code-executor/README.md b/backend/code-executor/README.md index 460d73207..d93900c28 100644 --- a/backend/code-executor/README.md +++ b/backend/code-executor/README.md @@ -1,3 +1,268 @@ +# Esecutore Codice (Code Executor) 🚀 + +Un sistema di ambiente isolato che supporta l'esecuzione di codice multi-linguaggio, può eseguire codice in sicurezza attraverso diversi ambienti runtime (come Aliyun Function Compute, processi locali, ecc.). + +## ✨ Caratteristiche Principali + +- **Supporto Multi-linguaggio**: Attualmente supporta PHP, Python e altri linguaggi di programmazione +- **Multi Ambiente Runtime**: Supporta Aliyun Function Compute e altri ambienti runtime +- **Isolamento Sicuro**: Esegue codice in ambienti indipendenti, garantendo la sicurezza del sistema +- **Alta Estensibilità**: Facile aggiungere supporto per nuovi linguaggi e ambienti runtime +- **API Semplice**: Design di interfaccia semplice e intuitiva + +## 📦 Installazione + +Installa tramite Composer: + +```bash +composer require dtyq/code-executor +``` + +## 🚀 Avvio Rapido + +### Uso Diretto + +```php + 'your-access-key-id', + 'secret_key' => 'your-access-key-secret', + 'region' => 'cn-hangzhou', + 'endpoint' => 'cn-hangzhou.fc.aliyuncs.com', +]; + +// Crea client runtime Aliyun +$runtimeClient = new AliyunRuntimeClient($config); + +// Crea esecutore +$executor = new AliyunExecutor($runtimeClient); + +// Inizializza ambiente di esecuzione +$executor->initialize(); + +// Crea richiesta di esecuzione +$request = new ExecutionRequest( + Language::PHP, + ' $sum, "a" => $a, "b" => $b]; + ', + [], // Parametri + 30 // Timeout (secondi) +); + +// Esegui codice +$result = $executor->execute($request); + +// Output risultato +echo "Output: " . $result->getOutput() . PHP_EOL; +echo "Tempo esecuzione: " . $result->getDuration() . "ms" . PHP_EOL; +echo "Risultato restituito: " . json_encode($result->getResult(), JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) . PHP_EOL; +``` + +### Uso in Hyperf + +Pubblica file di configurazione: + +```bash +php bin/hyperf.php vendor:publish dtyq/code-executor +``` + +Aggiungi variabili d'ambiente nel file `.env`: + +``` +CODE_EXECUTOR=aliyun +CODE_EXECUTOR_ALIYUN_ACCESS_KEY= +CODE_EXECUTOR_ALIYUN_SECRET_KEY= +CODE_EXECUTOR_ALIYUN_REGION=cn-shenzhen +CODE_EXECUTOR_ALIYUN_ENDPOINT= +CODE_EXECUTOR_ALIYUN_FUNCTION_NAME= +``` + +## 详细文档 + +### 核心组件 + +- **执行器(Executor)**：负责代码执行的主要组件 +- **运行时客户端(RuntimeClient)**：与具体执行环境通信的接口 +- **执行请求(ExecutionRequest)**：封装代码执行的请求信息 +- **执行结果(ExecutionResult)**：封装代码执行的结果信息 + +### 支持的语言 + +目前支持的编程语言： + +- PHP +- Python + +可通过扩展轻松添加更多语言支持。 + +### 支持的运行时环境 + +目前支持的运行时环境： + +- 阿里云函数计算 + +### 配置选项 + +#### 阿里云函数计算配置 + +```php +$config = [ + 'access_key' => 'your-access-key-id', // 阿里云AccessKey ID + 'secret_key' => 'your-access-key-secret', // 阿里云AccessKey Secret + 'region' => 'cn-hangzhou', // 地域ID + 'endpoint' => 'cn-hangzhou.fc.aliyuncs.com', // 服务接入点 + 'function' => [ + 'name' => 'test-code-runner', // 函数名称 + // 您可以在这里覆盖默认配置 + 'code_package_path' => __DIR__ . '/../runner', + ], +]; +``` + +## 示例 + +更多使用示例可在`examples`目录中找到： + +- `examples/aliyun_executor_example.php` - 阿里云函数计算执行器的完整示例 +- `examples/aliyun_executor_config.example.php` - 配置示例文件 + +运行示例： + +```bash +# 复制配置示例 +cp examples/aliyun_executor_config.example.php examples/aliyun_executor_config.php + +# 编辑配置文件 +vim examples/aliyun_executor_config.php + +# 运行示例 +php examples/aliyun_executor_example.php +``` + +## 扩展开发 + +### 添加新的语言支持 + +1. 在`Language`枚举中添加新的语言类型 +2. 在运行时客户端中实现对应的语言支持逻辑 + +### 添加新的运行时环境 + +1. 实现`RuntimeClient`接口 +2. 创建对应的`Executor`实现类 + +## 注意事项 + +1. 使用阿里云函数计算服务需要有有效的阿里云账号和正确的配置 +2. 代码执行可能产生费用，请注意控制资源使用 +3. 建议先在测试环境中验证后再用于生产环境 +4. `runner` 目录包含 `dtyq/code-runner-bwrap` 项目的源代码，该组件作为阿里云函数计算服务中的运行时环境。由于该组件尚未正式开源，目前直接内嵌在本项目中以确保功能完整性。待该组件正式开源后，仅需保留 `runner/bootstrap` 文件，其余部分可通过依赖方式引入 + +## 许可证 + +Apache License 2.0 + +--- + +## 📚 Documentazione Dettagliata + +### Componenti Core + +- **Esecutore(Executor)**: Componente principale responsabile dell'esecuzione del codice +- **Client Runtime(RuntimeClient)**: Interfaccia per comunicare con l'ambiente di esecuzione specifico +- **Richiesta Esecuzione(ExecutionRequest)**: Incapsula le informazioni della richiesta di esecuzione codice +- **Risultato Esecuzione(ExecutionResult)**: Incapsula le informazioni del risultato di esecuzione codice + +### Linguaggi Supportati + +Linguaggi di programmazione attualmente supportati: + +- PHP +- Python + +È possibile aggiungere facilmente supporto per più linguaggi attraverso estensioni. + +### Ambiente Runtime Supportati + +Ambiente runtime attualmente supportati: + +- Aliyun Function Compute + +### Opzioni di Configurazione + +#### Configurazione Aliyun Function Compute + +```php +$config = [ + 'access_key' => 'your-access-key-id', // Aliyun AccessKey ID + 'secret_key' => 'your-access-key-secret', // Aliyun AccessKey Secret + 'region' => 'cn-hangzhou', // ID Regione + 'endpoint' => 'cn-hangzhou.fc.aliyuncs.com', // Punto di accesso servizio + 'function' => [ + 'name' => 'test-code-runner', // Nome funzione + // Puoi sovrascrivere la configurazione predefinita qui + 'code_package_path' => __DIR__ . '/../runner', + ], +]; +``` + +## 💡 Esempi + +Altri esempi d'uso possono essere trovati nella directory `examples`: + +- `examples/aliyun_executor_example.php` - Esempio completo di esecutore Aliyun Function Compute +- `examples/aliyun_executor_config.example.php` - File esempio di configurazione + +Esegui esempi: + +```bash +# Copia file di configurazione esempio +cp examples/aliyun_executor_config.example.php examples/aliyun_executor_config.php + +# Modifica file di configurazione +vim examples/aliyun_executor_config.php + +# Esegui esempio +php examples/aliyun_executor_example.php +``` + +## 🔧 Sviluppo Estensioni + +### Aggiungere Supporto per Nuovi Linguaggi + +1. Aggiungi nuovo tipo di linguaggio nell'enum `Language` +2. Implementa la logica di supporto per il linguaggio corrispondente nel client runtime + +### Aggiungere Nuovo Ambiente Runtime + +1. Implementa l'interfaccia `RuntimeClient` +2. Crea la classe di implementazione `Executor` corrispondente + +## ⚠️ Note Importanti + +1. L'uso del servizio Aliyun Function Compute richiede un account Aliyun valido e configurazione corretta +2. L'esecuzione del codice potrebbe generare costi, presta attenzione al controllo dell'uso delle risorse +3. Si consiglia di verificare prima in ambiente di test prima di utilizzare in produzione +4. La directory `runner` contiene il codice sorgente del progetto `dtyq/code-runner-bwrap`, questo componente funge da ambiente runtime nel servizio Aliyun Function Compute. Poiché questo componente non è ancora ufficialmente open source, è attualmente incorporato direttamente in questo progetto per garantire l'integrità funzionale. Una volta che questo componente sarà ufficialmente open source, sarà necessario mantenere solo il file `runner/bootstrap`, mentre le altre parti potranno essere introdotte tramite dipendenze + +## 📄 Licenza + +Apache License 2.0 + +--- + # 代码执行器 (Code Executor) 一个支持多语言代码执行的隔离环境系统，可通过不同的运行时环境（如阿里云函数计算、本地进程等）安全地执行代码。 diff --git a/backend/easy-dingtalk/README.md b/backend/easy-dingtalk/README.md index 22693c613..f4755f4b2 100644 --- a/backend/easy-dingtalk/README.md +++ b/backend/easy-dingtalk/README.md @@ -1,3 +1,91 @@ +# Easy DingTalk 📱 + +

+ Latest Stable Version + Total Downloads + Build Status +

+ +Easy DingTalk è un SDK semplice e facile da usare per la piattaforma aperta DingTalk, supporta PHP 8.1+. Fornisce interfacce flessibili per interagire con la piattaforma aperta DingTalk, permettendo agli sviluppatori di costruire facilmente applicazioni DingTalk. + +## ✨ Caratteristiche + +- Supporta PHP 8.1+ +- Sviluppato basato sugli standard PSR +- Supporta integrazione con framework Hyperf +- Meccanismo flessibile di assemblaggio richieste +- Test unitari completi +- Supporta le principali interfacce della piattaforma aperta DingTalk + +## 📦 Installazione + +```bash +composer require dtyq/easy-dingtalk -vvv +``` + +## 🚀 Avvio Rapido + +### Uso Base + +```php +use Dtyq\EasyDingTalk\OpenDevFactory; + +$factory = new OpenDevFactory([ + 'app_key' => 'your_app_key', + 'app_secret' => 'your_app_secret', +]); + +// Ottieni token di accesso +$accessToken = $factory->getAccessToken(); + +// Usa altre interfacce... +``` + +### Integrazione Hyperf + +Aggiungi in `config/autoload/dependencies.php`: + +```php +return [ + Dtyq\EasyDingTalk\OpenDevFactory::class => function (ContainerInterface $container) { + return new Dtyq\EasyDingTalk\OpenDevFactory([ + 'app_key' => config('dingtalk.app_key'), + 'app_secret' => config('dingtalk.app_secret'), + ]); + }, +]; +``` + +## 🛠️ Sviluppo + +### Eseguire Test + +```bash +composer test +``` + +### Controllo Stile Codice + +```bash +composer cs-fix +``` + +### Analisi Statica + +```bash +composer analyse +``` + +## 🤝 Contributi + +Benvenuti a sottomettere Pull Request o creare Issue. + +## 📄 Licenza + +MIT + +--- + # Easy DingTalk

diff --git a/backend/flow-expr-engine/README.md b/backend/flow-expr-engine/README.md index a3607ad7b..e1379d53a 100644 --- a/backend/flow-expr-engine/README.md +++ b/backend/flow-expr-engine/README.md @@ -1,5 +1,48 @@

FlowExprEngine

+

Un potente motore di espressioni di flusso, utilizzato per creare e gestire componenti strutturati.

+ + +## 安装 + +```shell +$ composer require dtyq/flow-expr-engine -vvv +``` + +## 使用方法 + +```php +use Dtyq\FlowExprEngine\ComponentFactory; +use Dtyq\FlowExprEngine\Structure\StructureType; + +// 创建表单组件示例 +$formComponent = ComponentFactory::generateTemplate(StructureType::Form); + +// // Altri metodi d'uso... +``` + +## 📦 Installazione + +```shell +$ composer require dtyq/flow-expr-engine -vvv +``` + +## 🚀 Modalità d'Uso + +```php +use Dtyq\FlowExprEngine\ComponentFactory; +use Dtyq\FlowExprEngine\Structure\StructureType; + +// Esempio creazione componente form +$formComponent = ComponentFactory::generateTemplate(StructureType::Form); + +// Altri metodi d'uso... +``` + +--- + +

FlowExprEngine

+

一个强大的流程表达式引擎，用于创建和管理结构化组件。

@@ -19,4 +62,5 @@ use Dtyq\FlowExprEngine\Structure\StructureType; $formComponent = ComponentFactory::generateTemplate(StructureType::Form); // 更多使用方法... +``` `` \ No newline at end of file diff --git a/backend/super-magic-module/README.md b/backend/super-magic-module/README.md index cc4886223..0066d6c82 100644 --- a/backend/super-magic-module/README.md +++ b/backend/super-magic-module/README.md @@ -1,3 +1,182 @@ +# Super Magic Module - Modulo di Intelligenza Artificiale Avanzata 🚀 + +## Introduzione + +Super Magic Module è un pacchetto di estensioni basato sul framework Hyperf, progettato specificamente come modulo di estensione avanzata per magic-service. Questo modulo adotta l'architettura Domain-Driven Design (DDD), fornendo una struttura a strati chiara e componenti funzionali ricchi per le applicazioni. + +Super Magic Module deve essere utilizzato insieme a magic-service, e la sua funzionalità principale è quella di prendere il controllo degli eventi di messaggistica di magic-service, stabilendo un canale di comunicazione tra utenti e agenti intelligenti Super Magic. Questo design permette agli utenti di interagire senza soluzione di continuità con gli agenti intelligenti, ottenendo un'esperienza di servizio più intelligente. + +Come modulo ponte, Super Magic Module non solo gestisce la trasmissione dei messaggi, ma è anche responsabile della conversione dei formati dati, del coordinamento dei flussi di eventi e della fornitura delle informazioni contestuali necessarie, assicurando che gli agenti possano comprendere accuratamente le intenzioni degli utenti e fornire risposte appropriate. + +## Caratteristiche Principali + +- Costruito su Hyperf 3.1, perfettamente adattato all'architettura esistente di magic-service +- Segue l'architettura Domain-Driven Design (DDD), con organizzazione del codice chiara e facile da mantenere +- Fornisce funzionalità di condivisione risorse, supportando l'accesso alle risorse tra moduli +- Come canale di messaggistica, collega utenti e agenti intelligenti Super Magic +- Supporta l'ascolto e la gestione degli eventi, rispondendo in tempo reale alle richieste degli utenti +- Fornisce gestione dell'area di lavoro, supportando elaborazione multi-argomento e multi-task +- Implementa sistema di gestione file, supportando le operazioni degli agenti sui file +- Organizzazione del codice conforme agli standard PSR, garantendo la qualità del codice + +## Architettura di Sistema + +Super Magic Module come estensione di magic-service, gioca il seguente ruolo nel sistema complessivo: + +``` +Richiesta utente → magic-service → Super Magic Module → Agente Super Magic + ↑ | + └─────────────────┘ + Risposta di ritorno +``` + +Il modulo si integra con magic-service nei seguenti modi: + +1. Ascolta gli eventi di messaggistica di magic-service +2. Elabora e converte i formati dei messaggi +3. Trasmette i messaggi all'agente Super Magic +4. Riceve ed elabora le risposte dell'agente +5. Restituisce i risultati elaborati a magic-service + +## Installazione + +Installa tramite Composer: + +```bash +composer require dtyq/super-magic-module +``` + +## Utilizzo Base + +### Configurazione + +Il modulo fornisce `ConfigProvider` per registrare servizi e funzionalità correlati. Nella directory `config/autoload` dell'applicazione Hyperf configura: + +```php + [ + // Evento di esecuzione assistente + AgentExecuteInterface::class => SuperAgentMessageSubscriberV2::class, + SuperAgentMessageInterface::class => SuperAgentMessage::class, + ] +] +``` + +### Utilizzo del Livello Domain + +Il modulo è progettato basato sull'architettura DDD, comprendendo i seguenti livelli principali: + +- Domain (Livello Domain): Contiene logica di business e entità, come elaborazione messaggi, gestione area di lavoro e altre funzionalità core +- Application (Livello Applicazione): Coordina gli oggetti domain per completare scenari di business complessi, come flussi di trasmissione messaggi +- Infrastructure (Livello Infrastruttura): Fornisce supporto tecnico, inclusi archiviazione dati, chiamate servizi esterni, ecc. +- Interfaces (Livello Interfacce): Gestisce richieste e risposte esterne, fornisce interfacce API + +## Sviluppo + +### Struttura delle Directory + +``` +src/ +├── Application/ # Livello Applicazione, elabora flussi di business +│ ├── Share/ # Servizi di condivisione risorse +│ └── SuperAgent/ # Servizi agenti super intelligenti +├── Domain/ # Livello Domain, contiene logica di business core +│ ├── Share/ # Modelli domain di condivisione risorse +│ └── SuperAgent/ # Modelli domain agenti super intelligenti +├── Infrastructure/ # Livello Infrastruttura, fornisce implementazioni tecniche +│ ├── ExternalAPI/ # Chiamate API esterne +│ └── Utils/ # Classi di utilità +├── Interfaces/ # Livello Interfacce, gestisce interazioni esterne +│ ├── Share/ # Interfacce di condivisione risorse +│ └── SuperAgent/ # Interfacce agenti super intelligenti +├── Listener/ # Ascoltatori di eventi +└── ConfigProvider.php # Fornitore di configurazione +``` + +### Comandi + +Il pacchetto di estensioni fornisce una serie di comandi utili: + +```bash +# Riparazione stile codice +composer fix + +# Analisi statica codice +composer analyse + +# Esecuzione test +composer test + +# Avvio servizio Hyperf +composer start +``` + +## Flusso dei Messaggi + +Il flusso base di elaborazione dei messaggi di Super Magic Module è il seguente: + +1. L'utente invia un messaggio in magic-service +2. magic-service attiva l'evento messaggio +3. Super Magic Module ascolta l'evento, estrae il contenuto del messaggio +4. Il messaggio viene convertito nel formato comprensibile dall'agente Super Magic +5. Il messaggio viene inviato all'agente Super Magic +6. L'agente elabora il messaggio e genera una risposta +7. Super Magic Module riceve la risposta e converte il formato +8. La risposta viene trasmessa indietro a magic-service tramite evento +9. L'utente riceve la risposta dell'agente + +## Test + +Esegui i test: + +```bash +composer test +``` + +## Guida ai Contributi + +1. Fai il fork di questo repository +2. Crea un branch per la funzionalità (`git checkout -b feature/fantastica-funzionalita`) +3. Applica le modifiche (`git commit -m 'Aggiungi una fantastica funzionalità'`) +4. Fai il push del branch (`git push origin feature/fantastica-funzionalita`) +5. Crea una Pull Request + +## Risorse Correlate + +- [Documentazione ufficiale Hyperf](https://hyperf.wiki) +- [Standard PSR](https://www.php-fig.org/psr/) +- [Riferimento Domain-Driven Design](https://www.domainlanguage.com/ddd/) +- [Documentazione Magic Service](https://docs.dtyq.com/magic-service/) + +## Autori + +- **team dtyq** - [team@dtyq.com](mailto:team@dtyq.com) + +## Licenza + +Questo progetto utilizza una licenza privata - per i dettagli consulta la documentazione interna del team. + +## Stato del Progetto + +Questo modulo è in attivo sviluppo come componente di miglioramento di magic-service, fornendo continuamente aggiornamenti delle capacità di interazione intelligente. Accogliamo con favore feedback e suggerimenti dai membri del team per perfezionare insieme questo modulo chiave. + +--- + + + # Super Magic Module ## 简介 diff --git a/backend/tiptap/README.md b/backend/tiptap/README.md index 3b2268235..c77326928 100644 --- a/backend/tiptap/README.md +++ b/backend/tiptap/README.md @@ -1,3 +1,386 @@ +# Tiptap per PHP - Editor di Testo Ricco 🚀 +[![Ultima Versione su Packagist](https://img.shields.io/packagist/v/ueberdosis/tiptap-php.svg?style=flat-square)](https://packagist.org/packages/ueberdosis/tiptap-php) +[![Stato Test GitHub](https://github.com/ueberdosis/tiptap-php/actions/workflows/run-tests.yml/badge.svg)](https://github.com/ueberdosis/tiptap-php/actions/workflows/run-tests.yml) +[![Download Totali](https://img.shields.io/packagist/dt/ueberdosis/tiptap-php.svg?style=flat-square)](https://packagist.org/packages/ueberdosis/tiptap-php) +[![Licenza](https://img.shields.io/packagist/l/ueberdosis/tiptap-php?style=flat-square)](https://packagist.org/packages/ueberdosis/tiptap-php) +[![Chat](https://img.shields.io/badge/chat-su%20discord-7289da.svg?sanitize=true)](https://discord.gg/WtJ49jGshW) +[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis) + +Un pacchetto PHP per lavorare con contenuti [Tiptap](https://tiptap.dev/). Puoi trasformare JSON compatibile con Tiptap in HTML, e viceversa, sanificare i tuoi contenuti, o semplicemente modificarli. + +## Installazione +Puoi installare il pacchetto tramite composer: + +```bash +composer require ueberdosis/tiptap-php +``` + +## Utilizzo +Il pacchetto PHP imita gran parte del pacchetto JavaScript. Se conosci Tiptap, la sintassi PHP ti sembrerà familiare. + +### Converti HTML Tiptap in JSON +Iniziamo convertendo uno snippet HTML in un array PHP con struttura compatibile Tiptap: + +```php +(new \Tiptap\Editor) + ->setContent('

Testo Esempio

') + ->getDocument(); + +// Restituisce: +// ['type' => 'doc', 'content' => …] +``` + +Puoi ottenere anche una stringa JSON in PHP. + +```php +(new \Tiptap\Editor) + ->setContent('

Testo Esempio

') + ->getJSON(); + +// Restituisce: +// {"type": "doc", "content": …} +``` + +### Converti JSON Tiptap in HTML +L'altra direzione funziona altrettanto bene. Basta passare una stringa JSON o un array PHP per generare l'HTML. + +```php +(new \Tiptap\Editor) + ->setContent([ + 'type' => 'doc', + 'content' => [ + [ + 'type' => 'paragraph', + 'content' => [ + [ + 'type' => 'text', + 'text' => 'Testo Esempio', + ], + ] + ] + ], + ]) + ->getHTML(); + +// Restituisce: +//

Testo Esempio

+``` + +Questo non aderisce completamente allo schema ProseMirror. Alcune cose sono supportate troppo, ad esempio i segni non sono consentiti in un `CodeBlock`. + +Se hai bisogno di un migliore supporto schema, crea un issue con la funzionalità che ti manca. + +### Evidenziazione sintassi per blocchi di codice con [highlight.php](https://github.com/scrivo/highlight.php) +L'estensione `CodeBlock` predefinita non aggiunge evidenziazione sintassi ai tuoi blocchi di codice. Tuttavia, se vuoi aggiungere evidenziazione sintassi ai tuoi blocchi di codice, c'è un'estensione speciale `CodeBlockHighlight`. + +Sostituire quella predefinita funziona così: + +```php +(new \Tiptap\Editor([ + 'extensions' => [ + new \Tiptap\Extensions\StarterKit([ + 'codeBlock' => false, + ]), + new \Tiptap\Nodes\CodeBlockHighlight(), + ], +])) +->setContent('
<?php phpinfo()
') +->getHTML(); + +// Restituisce: +// 
<?php phpinfo()
+``` + +Questo è ancora senza stile. Devi [caricare un file CSS](https://highlightjs.org/download/) per aggiungere colori all'output, ad esempio così: + +```html + +``` + +Boom, evidenziazione sintassi! A proposito, questo è alimentato dall'incredibile [scrivo/highlight.php](https://github.com/scrivo/highlight.php). + +### Evidenziazione sintassi per blocchi di codice con [Shiki](https://github.com/shikijs/shiki) (Richiede Node.js) +C'è un evidenziatore di sintassi alternativo che utilizza [Shiki](https://github.com/shikijs/shiki). Shiki è un bellissimo evidenziatore di sintassi alimentato dallo stesso motore linguistico utilizzato da molti editor di codice. Le principali differenze dall'estensione `CodeBlockHighlight` sono: 1) devi installare il pacchetto npm `shiki`, 2) l'evidenziazione del codice Shiki funziona iniettando stili inline quindi non è necessario tirare un file css esterno, 3) puoi usare la maggior parte dei temi VS Code per evidenziare il tuo codice. + +Per usare l'estensione Shiki, prima installa il pacchetto npm + +```bash +npm install shiki +``` + +Poi segui l'esempio sotto: + +```php +(new \Tiptap\Editor([ + 'extensions' => [ + new \Tiptap\Extensions\StarterKit([ + 'codeBlock' => false, + ]), + new \Tiptap\Nodes\CodeBlockShiki, + ], +])) +->setContent('
<?php phpinfo()
') +->getHTML(); +``` + +Per configurare il tema o il linguaggio predefinito per i blocchi di codice, passa configurazioni aggiuntive nel costruttore come mostrato sotto: + +```php +(new \Tiptap\Editor([ + 'extensions' => [ + new \Tiptap\Extensions\StarterKit([ + 'codeBlock' => false, + ]), + new \Tiptap\Nodes\CodeBlockShiki([ + 'theme' => 'github-dark', // default: nord, vedi https://github.com/shikijs/shiki/blob/main/docs/themes.md + 'defaultLanguage' => 'php' // default: html, vedi https://github.com/shikijs/shiki/blob/main/docs/languages.md + 'guessLanguage' => true // default: true, se il linguaggio non è passato, prova a indovinarlo con highlight.php + ]), + ], +])) +->setContent('
<?php phpinfo()
') +->getHTML(); +``` + +Sotto il cofano l'estensione Shiki utilizza [Shiki PHP di Spatie](https://github.com/spatie/shiki-php), quindi consulta la documentazione per dettagli e considerazioni aggiuntive. + +### Converti contenuto in testo semplice +Il contenuto può anche essere trasformato in testo semplice, ad esempio per metterlo in un indice di ricerca. + +```php +(new \Tiptap\Editor) + ->setContent('

Titolo

Paragrafo

') + ->getText(); + +// Restituisce: +// "Titolo +// +// Paragrafo" +``` + +Quello che viene tra i blocchi può essere configurato, anche. + +```php +(new \Tiptap\Editor) + ->setContent('

Titolo

Paragrafo

') + ->getText([ + 'blockSeparator' => "\n", + ]); + +// Restituisce: +// "Titolo +// Paragrafo" +``` + +### Sanifica contenuto +Un ottimo caso d'uso per il pacchetto PHP è pulire (o "sanificare") il contenuto. Puoi farlo con il metodo `sanitize()`. Funziona con stringhe JSON, array PHP e HTML. + +Restituirà lo stesso formato che stai usando come formato di input. + +```php +(new \Tiptap\Editor) + ->sanitize('

Testo Esempio

'); + +// Restituisce: +// '

Testo Esempio

' +``` + +### Modificare il contenuto +Con il metodo `descendants()` puoi scorrere tutti i nodi ricorsivamente come sei abituato dal pacchetto JavaScript. Ma in PHP, puoi persino modificare il nodo per aggiornare attributi e tutto il resto. + +> Avvertimento: Devi aggiungere `&` al parametro. Questo mantiene un riferimento all'elemento originale e permette di modificare quello originale, invece di solo una copia. + +```php +$editor->descendants(function (&$node) { + if ($node->type !== 'heading') { + return; + } + + $node->attrs->level = 1; +}); +``` + +### Configurazione +Passa la configurazione al costruttore dell'editor. Non c'è molto da configurare, ma almeno puoi passare il contenuto iniziale e caricare estensioni specifiche. + +```php +new \Tiptap\Editor([ + 'content' => '

Testo Esempio

', + 'extensions' => [ + new \Tiptap\Extensions\StarterKit, + ], +]) +``` + +Il `StarterKit` è caricato per default. Se vuoi usare solo quello, non c'è bisogno di impostarlo. + +### Estensioni +Per default, è caricato lo [`StarterKit`](https://tiptap.dev/api/extensions/starter-kit), ma puoi passare un array personalizzato di estensioni. + +```php +new \Tiptap\Editor([ + 'extensions' => [ + new \Tiptap\Extensions\StarterKit, + new \Tiptap\Marks\Link, + ], +]) +``` + +### Configura estensioni +Alcune estensioni possono essere configurate. Basta passare un array al costruttore, ecco fatto. Miriamo a supportare la stessa configurazione del pacchetto JavaScript. + +```php +new \Tiptap\Editor([ + 'extensions' => [ + // … + new \Tiptap\Nodes\Heading([ + 'levels' => [1, 2, 3], + ]), + ], +]) +``` + +Puoi passare attributi HTML personalizzati attraverso la configurazione, anche. + +```php +new \Tiptap\Editor([ + 'extensions' => [ + // … + new \Tiptap\Nodes\Heading([ + 'HTMLAttributes' => [ + 'class' => 'my-custom-class', + ], + ]), + ], +]) +``` + +Per lo `StarterKit`, è leggermente diverso, ma funziona come sei abituato dal pacchetto JavaScript. + +```php +new \Tiptap\Editor([ + 'extensions' => [ + new Tiptap\Extensions\StarterKit([ + 'codeBlock' => false, + 'heading' => [ + 'HTMLAttributes' => [ + 'class' => 'my-custom-class', + ], + ] + ]), + ], +]) +``` + +### Estendi estensioni esistenti +Se hai bisogno di cambiare piccoli dettagli delle estensioni supportate, puoi semplicemente estendere un'estensione. + +```php + invece di + return ['b', 0] + } +} + +new \Tiptap\Editor([ + 'extensions' => [ + new Paragraph, + new Text, + new CustomBold, + ], +]) +``` + +#### Estensioni personalizzate +Puoi persino costruire estensioni personalizzate. Se sei abituato all'API JavaScript, sarai sorpreso di quanto di quello funzioni anche in PHP. 🤯 Dai un'occhiata agli esempi nelle estensioni di questo repository per saperne di più sull'API delle estensioni PHP. + +```php + [], + ]; + } + + public function parseHTML() + { + return [ + [ + 'tag' => 'my-custom-tag[data-id]', + ], + [ + 'tag' => 'my-custom-tag', + 'getAttrs' => function ($DOMNode) { + return ! \Tiptap\Utils\InlineStyle::hasAttribute($DOMNode, [ + 'background-color' => '#000000', + ]) ? null : false; + }, + ], + [ + 'style' => 'background-color', + 'getAttrs' => function ($value) { + return (bool) preg_match('/^(black)$/', $value) ? null : false; + }, + ], + ]; + } + + public function renderHTML($node) + { + return ['my-custom-tag', ['class' => 'foobar'], 0] + } +} +``` + +#### Priorità delle estensioni + +Le estensioni sono valutate nell'ordine di priorità decrescente. Per default, tutti i Nodes, Marks e Extensions hanno un valore di priorità di `100`. + +La priorità dovrebbe essere definita quando si crea un'estensione Node per corrispondere al markup che potrebbe essere corrisposto da altri Nodes - un esempio di questo è il [TaskItem Node](src/Nodes/TaskItem.php) che ha priorità di valutazione sul [ListItem Node](src/Nodes/ListItem.php). + +## Test +```bash +composer test +``` + +Puoi installare nodemon (`npm install -g nodemon`) per mantenere la suite di test in esecuzione e guardare i cambiamenti dei file: + +```bash +composer test-watch +``` + +## Contributi +Consulta [CONTRIBUTING](.github/CONTRIBUTING.md) per i dettagli. + +## Vulnerabilità di Sicurezza +Consulta [la nostra policy di sicurezza](../../security/policy) su come segnalare vulnerabilità di sicurezza. + +## Crediti +- [Hans Pagel](https://github.com/hanspagel) +- [Tutti i Contributori](../../contributors) + +## Licenza +La Licenza MIT (MIT). Consulta [File Licenza](LICENSE.md) per maggiori informazioni. + +--- + + + # Tiptap for PHP [![Latest Version on Packagist](https://img.shields.io/packagist/v/ueberdosis/tiptap-php.svg?style=flat-square)](https://packagist.org/packages/ueberdosis/tiptap-php) [![GitHub Tests Action Status](https://github.com/ueberdosis/tiptap-php/actions/workflows/run-tests.yml/badge.svg)](https://github.com/ueberdosis/tiptap-php/actions/workflows/run-tests.yml) diff --git a/docs/README.md b/docs/README.md index ced142fcb..798a32703 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,28 @@ +Prerequisiti 📋 + +Node.js versione 18 o superiore. ⬆️ +Terminale per accedere a VitePress tramite la sua interfaccia a riga di comando (CLI). 🖥️ +Editor di testo con supporto per la sintassi Markdown. ✍️ +Si consiglia VSCode, insieme all'estensione ufficiale per Vue. 💡 + + +VitePress può essere usato da solo oppure installato in un progetto esistente. In entrambi i casi, puoi installarlo con: 🧩 + +`npm add -D vitepress` + +Lo script docs:dev avvierà un server di sviluppo locale con aggiornamenti hot immediati. Eseguilo con il comando seguente: 🚀 + + + +`npm run docs:dev` + +Invece degli script npm, puoi anche avviare VitePress direttamente con: ▶️ + +`npx vitepress dev docs` + + +Testo originale (English) — mantenuto sotto: + Prerequisites Node.js version 18 or higher. diff --git a/docs/en/index.md b/docs/en/index.md index f35594144..cfee72208 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -2,6 +2,37 @@ # https://vitepress.dev/reference/default-theme-home-page layout: home +hero: + name: "Magic ✨" + text: "Il nuovo motore di innovazione per applicazioni AI a livello enterprise" + tagline: "Crea facilmente potenti applicazioni AI 🚀" + actions: + - theme: brand + text: "Tutorial 📘" + link: /en/tutorial/magic-info/ + - theme: alt + text: "Sviluppo 🛠️" + link: /en/development/quick-start/quick-introduction.md + +# features: +# - icon: 🚀 +# title: Veloce ed efficiente +# details: Con la performance al centro, Magic Docs fornisce siti di documentazione ultraveloce. +# - icon: 🎨 +# title: Design elegante +# details: Design moderno e pulito che si adatta perfettamente a tutti i dispositivi. +# - icon: 🔧 +# title: Facile da usare +# details: Configurazione semplice e funzionalità potenti rendono la creazione di documentazione professionale senza sforzo. +--- + +Versione originale (inglese) mantenuta sotto per riferimento: + +```yaml +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + hero: name: "Magic" text: "The New Generation Enterprise-level AI Application Innovation Engine" @@ -24,4 +55,5 @@ hero: # - icon: 🔧 # title: Easy to Use # details: Simple configuration and powerful features make creating professional documentation effortless. ---- \ No newline at end of file +--- +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 50ee67d6f..df84ee730 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,50 @@ # https://vitepress.dev/reference/default-theme-home-page layout: home +# Aggiungi script di rilevamento della lingua 🌐 +head: + - - script + - {} + - | + // Rileva la lingua del browser e reindirizza + (function() { + var userLang = navigator.language || navigator.userLanguage; + var path = userLang.startsWith('zh') ? '/zh/' : '/en/'; + // Reindirizza solo dalla radice per evitare reindirizzamenti ripetuti + if (window.location.pathname === '/' || window.location.pathname === '/index.html') { + window.location.href = path; + } + })(); + +hero: + name: "Magic" + text: "La nuova generazione di motore di innovazione per applicazioni AI a livello enterprise" + tagline: "Crea potenti applicazioni AI con facilità ✨🤖" + actions: + - theme: brand + text: "Tutorial 📘" + link: /en/tutorial/quick-start/quick-introduction.md + - theme: alt + text: "Guida allo sviluppo 🛠️" + link: /en/development/quick-start/quick-introduction.md + +# features: +# - icon: 🚀 +# title: Veloce e Efficiente +# details: Progettato per le prestazioni, Magic Docs offre siti di documentazione estremamente veloci. +# - icon: 🎨 +# title: Design Accattivante +# details: Design moderno e pulito che funziona bene su tutti i dispositivi. +# - icon: 🔧 +# title: Facile da Usare +# details: Configurazione semplice e funzionalità potenti per creare documentazione professionale. +--- + + +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + # 添加语言自动检测脚本 head: - - script diff --git a/frontend/eslint-config/README.md b/frontend/eslint-config/README.md index 4b844da28..9fde2dd51 100644 --- a/frontend/eslint-config/README.md +++ b/frontend/eslint-config/README.md @@ -1,3 +1,103 @@ +# @dtyq/eslint-config 🔧 + +Pacchetto di configurazione ESLint per principianti, con tutte le dipendenze integrate, senza bisogno di installare ESLint e plugin correlati aggiuntivi. + +## ✨ Caratteristiche + +- ✅ Configurazione zero: Pronto all'uso, tutto in un passo +- ✅ Dipendenze integrate: Non richiede l'installazione di pacchetti ESLint aggiuntivi +- ✅ Configurazioni multiple: Supporta scenari base, TypeScript, React, Vue e altri +- ✅ Compatibile con pnpm workspace + +## 🏢 Uso in pnpm workspace + +1. Aggiungi la dipendenza nel `package.json` del pacchetto che necessita ESLint: + +```json +{ + "devDependencies": { + "@dtyq/eslint-config": "workspace:*" + } +} +``` + +2. Crea il file `eslint.config.js`: + +```javascript +// Uso più semplice (raccomandato) +import { createRequire } from 'module'; +const require = createRequire(import.meta.url); + +// Utilizza direttamente la configurazione predefinita, risolto in una riga +const typescriptPreset = require('@dtyq/eslint-config/typescript-preset'); + +export default [ + { ...typescriptPreset }, + // Regole personalizzate (opzionale) + { + files: ['src/**/*.ts'], + rules: { + // Regole personalizzate + } + } +]; +``` + +```javascript +// Uso avanzato (combinazione di configurazioni multiple) +import { createRequire } from 'module'; +const require = createRequire(import.meta.url); + +const baseConfig = require('@dtyq/eslint-config/base'); +const typescriptConfig = require('@dtyq/eslint-config/typescript'); + +export default [ + { ...baseConfig }, + { ...typescriptConfig }, + // Regole personalizzate + { + files: ['src/**/*.ts'], + rules: { + // Regole personalizzate + } + } +]; +``` + +```javascript +// Progetto CommonJS +const baseConfig = require('@dtyq/eslint-config/base'); + +module.exports = { + ...baseConfig, + // Regole personalizzate +}; +``` + +3. Aggiungi script lint al `package.json`: + +```json +{ + "scripts": { + "lint": "eslint --config eslint.config.js 'src/**/*.{js,ts,tsx}'" + } +} +``` + +## 📋 Configurazioni Disponibili + +- `@dtyq/eslint-config` - Configurazione predefinita +- `@dtyq/eslint-config/base` - Regole base +- `@dtyq/eslint-config/typescript` - Regole TypeScript +- `@dtyq/eslint-config/typescript-preset` - Preset progetto TypeScript (include regole base e TS, raccomandato) +- `@dtyq/eslint-config/react` - Regole React +- `@dtyq/eslint-config/vue` - Regole Vue 3.x +- `@dtyq/eslint-config/vue2` - Regole Vue 2.x +- `@dtyq/eslint-config/prettier` - Integrazione Prettier +- `@dtyq/eslint-config/jsconfig` - Supporto jsconfig.json + +--- + # @dtyq/eslint-config 傻瓜式 ESLint 配置包，内置所有依赖，无需额外安装 ESLint 及相关插件。 diff --git a/frontend/magic-flow/README.md b/frontend/magic-flow/README.md index a4e1d4610..e54dbddfb 100644 --- a/frontend/magic-flow/README.md +++ b/frontend/magic-flow/README.md @@ -1,3 +1,88 @@ +# Magic Flow - Pacchetto Fondamentale per Flussi ✨ + +
+ Stato: Sviluppo + Framework: React + Licenza: MIT +
+ +## 📖 Introduzione al Progetto + +Magic Flow è una libreria fondamentale per la gestione di flussi, estratta da Magic Flow e pronta all'uso. Basata su ReactFlow, offre potenti funzionalità di progettazione e gestione di diagrammi di flusso. Il progetto integra componenti di base per i flussi, un editor JSON Schema, componenti per espressioni e UI comuni interne, per aiutarti a costruire rapidamente applicazioni di flusso visuali. 🚀 + +## ✨ Caratteristiche Principali + +- 🔄 Progettazione e gestione di diagrammi di flusso basata su ReactFlow +- 🎯 Gestione ad alte prestazioni di nodi e connessioni (batch e ottimizzazione debounce) +- 🧩 Sistema di tipi di nodi estendibile +- 🔍 Modifica di form basati su JSON Schema +- 🌐 Supporto multilingua +- 🎨 Componenti UI belli e personalizzabili + +## 📦 Installazione + +```bash +# Installa le dipendenze +npm install @dtyq/magic-flow +``` + +## 📚 Guida all'Uso + +Al momento non esiste una guida rapida unificata. Per usare i componenti, consulta queste risorse: + +- Consulta il file `index.md` nella cartella di ciascun componente per istruzioni dettagliate +- Guarda i progetti di esempio nella cartella `examples` per capire gli scenari applicativi +- Ogni componente ha codice di esempio di riferimento + +Ad esempio, per imparare a usare il componente `MagicFlow`: +1. Consulta il file `src/MagicFlow/index.md` +2. Guarda i progetti di esempio in `examples/MagicFlow` + +## 📚 Documentazione API + +### Componenti Principali + +- `MagicFlow`: Componente principale per la progettazione dei flussi +- `MagicJsonSchemaEditor`: Generatore di form basato su Schema +- `MagicExpressionWidget`: Componente per la creazione e modifica di espressioni +- `MagicConditionEdit`: Componente per la modifica delle condizioni + +### Core Hooks + +- `useBaseFlow`: Hook logico principale per la gestione di nodi e connessioni +- `useNodeBatchProcessing`: Hook per il batch dei nodi, migliora le performance con molti nodi + +### Documentazione Dettagliata ed Esempi + +- Ogni componente ha una documentazione dettagliata: consulta il file `index.md` nella cartella del componente +- Il componente `MagicFlow` offre molti casi reali: guarda i progetti di esempio nella cartella `examples` +- Gli esempi mostrano l'uso pratico del designer di flussi in vari scenari, inclusa la personalizzazione dei nodi e la configurazione dei form + +## 🛠️ Sviluppo + +```bash +# Installa le dipendenze +npm install + +# Avvia la demo della documentazione per lo sviluppo +npm start + +# Costruisci la libreria +npm run build +``` + +## 🤝 Guida al Contributo + +Contribuisci con codice o segnala problemi! Fai prima il fork del repository, poi invia una Pull Request. 💡 + +## 📄 Licenza + +MIT + +--- + + + # 神奇流程基础包
diff --git a/frontend/magic-web/README.md b/frontend/magic-web/README.md index 47054f3e2..e0f6f1a6d 100644 --- a/frontend/magic-web/README.md +++ b/frontend/magic-web/README.md @@ -1,3 +1,115 @@ +# Magic - Guida allo Sviluppo 🚀 + +## Ambiente di sviluppo + +- Node.js: usa l'ultima versione stabile (v18+) +- pnpm: v9+ + +## Avvio rapido + +```bash +# Installa le dipendenze +pnpm install + +# Avvia il server di sviluppo +pnpm dev + +# Costruisci la versione di produzione +pnpm build + +# Esegui i test +pnpm test +``` + +## Stack tecnologico + +- React +- Vite +- Zustand +- SWR +- Antd + +## Linee guida di sviluppo + +### Stile del codice + +- Il progetto usa ESLint e Prettier per la formattazione del codice +- Prima di fare commit, assicurati che tutti i lint siano superati +- I file dei componenti usano la notazione PascalCase +- I file delle funzioni di utilità usano la notazione camelCase + +### Sviluppo dei componenti + +#### Scrittura degli stili + +Gli stili seguono le regole di `ant-design@5.x` e l'approccio `CSS-in-JS`. Prima di usarli, consulta la [guida ufficiale antd-style](https://ant-design.github.io/antd-style/guide/create-styles). In questo progetto, segui queste regole: + +- Separa gli stili dai componenti: esempio `useStyle.ts` e `Component.tsx` +- Non usare `less`, `styled-components` o altri plugin/moduli di stile di terze parti +- Non usare plugin come `classnames` o `clsx`, usa sempre `const { styles, cx } = useStyle();` e `cx` per attivare gli stili + +#### Componenti comuni + +- Componenti di base: alcuni componenti di base di antd sono stati estesi e migliorati, si trovano in `src/components/base`, usali preferibilmente +- Componenti di business: componenti usati spesso nelle logiche di business, si trovano in `src/components/business` + +#### Principi di sviluppo dei componenti + +- I componenti devono essere riutilizzabili, evita l'eccessivo accoppiamento con la logica di business +- Ogni componente deve avere una definizione di tipo completa +- I componenti complessi devono avere una documentazione d'uso +- Segui il principio della singola responsabilità + +### Git workflow + +- Branch principale: `released` (TODO) +- Branch pre-release: `pre-release` (TODO) +- Branch di test: `master` +- Branch funzionalità: `feature/nome-funzionalità` +- Branch fix: `hotfix/descrizione-problema` + +Formato dei messaggi di commit: + +``` +type(scope): commit message + +- type: feat|fix|docs|style|refactor|test|chore +- scope: area interessata +- message: descrizione del commit +``` + +### Test unitari + +Framework di test: [Vitest](https://cn.vitest.dev/) + +Per ogni funzione di utilità, aggiungi quanti più test possibili per garantire robustezza e ridurre i costi di manutenzione futura. + +I file di test vanno nella cartella `__tests__` accanto alla funzione, con nome `{filename}.test.ts`. + +#### Regole per i test + +- Ogni funzione di utilità deve avere test dedicati +- I test devono coprire sia i casi normali che quelli anomali +- Le descrizioni dei test devono essere chiare +- Usa `describe` e `it` per organizzare i test + +### Consigli di sviluppo + +1. Prima di iniziare, leggi tutto questo documento +2. In caso di problemi, consulta prima la documentazione del progetto e delle dipendenze +3. Quando sviluppi nuove funzionalità, definisci prima i tipi +4. Prima di fare commit, testa tutto e assicurati che i test passino + +## Estensioni VSCode consigliate + +- i18n Ally +- Vitest, Vitest Runner +- Git Graph + +--- + + + # Magic ## 开发环境 diff --git a/frontend/upload-sdk/README.md b/frontend/upload-sdk/README.md index b19fdbb72..4f28f0649 100644 --- a/frontend/upload-sdk/README.md +++ b/frontend/upload-sdk/README.md @@ -1,3 +1,133 @@ +# Upload SDK 📤 + +Componente di upload unificato che fornisce supporto per Aliyun OSS, Volcano TOS, Huawei OBS e altri, con espansione continua per supportare Tencent COS, Qiniu Kodo, Baidu BOS, Netease NOS e altre capacità di upload. + +## 🚀 Avvio Rapido + +① Installa @dtyq/upload-sdk + +```bash +npm install @dtyq/upload-sdk +``` + +② Utilizza upload-sdk per caricare file, ecco un esempio base: + +```ts +const uploadTask = uploadSDK.upload({ + url: "your back-end interface", + method: "GET", + file: yourFile, // file + fileName: yourFileName, // nome file + headers: { + "request-id": Date.now(), + }, +}); +if (uploadTask.success) { + uploadTask.success((res: result) => + console.log(`Upload completato：${JSON.stringify(res)}`), + ); +} +if (uploadTask.progress) { + uploadTask.progress((precent, loaded, total) => + console.log(`Progresso upload file：${precent}%`, loaded, total), + ); +} +if (uploadTask.fail) { + uploadTask.fail((response) => console.log("- fail response -", response)); +} + +// ---------- Singolo task di upload ---------- +// Annulla upload +uploadTask.cancel(); +// Pausa upload +uploadTask.pause(); +// Riprendi upload +uploadTask.resume(); +``` + +## 🔄 Flusso di Upload + +```mermaid +--- +title: Upload SDK Upload Flow +--- + +sequenceDiagram + Applicazione frontend-->>UploadSdk: Passa configurazione credenziali + UploadSdk->>Applicazione backend: Invia richiesta, richiede credenziali upload temporanee + Applicazione backend->>Servizio base: Integra parametri necessari (come platform, bucket, ecc.), richiede credenziali upload temporanee + Servizio base->>Applicazione backend: Restituisce credenziali upload temporanee + Applicazione backend-->>UploadSdk: Restituisce credenziali upload temporanee + UploadSdk-->>Piattaforma cloud: Carica file + Piattaforma cloud-->>Servizio base: Attiva callback upload (Aliyun) + Piattaforma cloud-->>UploadSdk: Upload riuscito + UploadSdk-->>Applicazione frontend: Restituisce parametri platform, path, ecc. + Applicazione frontend-->>Applicazione backend: Memorizza informazioni path, ecc. +``` + +PS: Callback upload, Volcano attualmente non supportato, ma non influisce sul flusso. + +## ⚡ Caratteristiche di Ottimizzazione Prestazioni + +### Code Splitting e Caricamento On-Demand + +Dalla versione x.x.x, upload-sdk supporta code splitting e caricamento on-demand dei moduli platform. Questo significa che durante l'inizializzazione non verranno caricati tutti gli adattatori delle piattaforme cloud storage, ma solo quando effettivamente necessari, riducendo il volume del pacchetto iniziale e migliorando le prestazioni di avvio dell'applicazione. + +#### Modalità d'Uso + +Utilizza import asincrono (raccomandato): + +```typescript +import { Upload, loadPlatformModule, PlatformType } from "@dtyq/upload-sdk"; + +// Precarica moduli platform specifici (opzionale) +async function preloadModules() { + // Carica solo i moduli platform necessari + await loadPlatformModule(PlatformType.ALiYun); + console.log("Modulo Aliyun caricato"); +} + +// O carica automaticamente durante l'upload +const upload = new Upload(); +upload.upload({ + url: "your-api-url", + method: "POST", + file: yourFile, + fileName: "example.jpg", + // ... altre configurazioni +}); +``` + +Utilizza modalità compatibilità (retrocompatibile): + +```typescript +import { Upload } from "@dtyq/upload-sdk"; + +// Continua ad utilizzare il metodo originale, SDK caricherà automaticamente moduli on-demand internamente +const upload = new Upload(); +// ... altro codice rimane invariato +``` + +## 🌐 Piattaforme Supportate + +La tabella seguente elenca le piattaforme cloud storage attualmente supportate e quelle pianificate per versioni future: + +| Piattaforma | Stato | Descrizione | +| ----------- | ----------- | ------------------------------ | +| Aliyun OSS | ✅ Supportato | Supporta upload frammentato, resume, ecc. | +| Volcano TOS | ✅ Supportato | Supporta upload frammentato, resume, ecc. | +| Huawei OBS | ✅ Supportato | Supporta upload frammentato, resume, ecc. | +| Qiniu Kodo | ✅ Supportato | Attualmente supporta upload base | +| Tencent COS | 🔄 Pianificato | In sviluppo | +| Baidu BOS | 🔄 Pianificato | In sviluppo | +| Netease NOS | 🔄 Pianificato | In sviluppo | +| AWS S3 | 🔄 Pianificato | In sviluppo | +| Azure Blob | 🔄 Pianificato | In sviluppo | + +> Nota: Per piattaforme non ancora supportate, puoi aiutarci ad accelerare lo sviluppo inviando Issue o PR. + +--- + # Upload SDK 统一上传组件，提供阿里云OSS、火山云TOS、华为云OBS等，后续持续扩展支持腾讯云COS、七牛云Kodo、百度BOS、网易NOS等上传能力。 From 30d4240cdf639b805b69f8d1a15a3c004cf6a214 Mon Sep 17 00:00:00 2001 From: astrolabz Date: Sat, 30 Aug 2025 01:23:38 +0200 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=94=84=20Aggiornamento=20Parziale=20T?= =?UTF-8?q?raduzioni=20Italiane=20e=20Verifica=20Sistematica?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 📋 RIEPILOGO MODIFICHE: Questa commit include un lavoro estensivo di traduzione e verifica sistematica di file di documentazione .md nel progetto Magic Flow. 🏆 RISULTATO: Completamento totale della verifica sistematica dei file .md che necessitavano traduzione italiana. Tutti i file sono stati verificati e risultano già tradotti correttamente secondo le regole stabilite. --- .github/ISSUE_TEMPLATE/README.md | 100 ++- .gitignore | 1 + CONTRIBUTING_CN.md | 99 +++ README_CN.md | 208 +++++- backend/code-executor/examples/README.md | 88 ++- backend/magic-gateway/README.md | 501 +++++++++++++++ backend/magic-gateway/README_HEADERS.md | 104 +++ backend/magic-gateway/README_JWT_SECURITY.md | 214 ++++++- .../docs/multi-environment-deployment.md | 429 ++++++++++++- backend/magic-service/README.md | 138 +++- .../app/Interfaces/Asr/CHANGELOG.md | 74 ++- .../magic-service/storage/prompt/tool_call.md | 42 +- backend/rule-engine-core/README.md | 207 ++++++ backend/sandbox-gateway/README.md | 190 ++++++ backend/sdk-base/README.md | 18 +- backend/super-magic/README.md | 57 ++ .../guides/config_management_guide.md | 157 +++++ .../guides/dotenv_configuration.md | 30 + .../super-magic/guides/event_system_guide.md | 260 ++++++++ backend/super-magic/guides/super_magic.md | 310 +++++++++ .../guides/tools_architecture_guide.md | 378 +++++++++++ backend/task-scheduler/README.md | 124 ++++ backend/tiptap/.github/CONTRIBUTING.md | 52 ++ backend/tiptap/.github/SECURITY.md | 6 + docs/en/development/advanced/init.md | 62 +- docs/en/development/advanced/permission.md | 188 ++++++ docs/en/development/deploy/docker.md | 69 +- docs/en/development/deploy/environment.md | 347 ++++++++++ docs/en/development/deploy/file-driver.md | 261 +++++++- docs/en/development/deploy/super-magic.md | 215 +++++++ .../quick-start/quick-introduction.md | 433 ++++++++++++- docs/en/development/version/changelog.md | 30 +- .../development/version/release-planning.md | 22 + docs/en/development/version/versions.md | 19 +- .../quick-start/quick-introduction.md | 50 +- docs/zh/index.md | 32 + docs/zh/tutorial/basic/end-node.md | 108 ++++ docs/zh/tutorial/basic/flow/build-a-flow.md | 19 + .../basic/flow/use-flow-with-openai.md | 28 + docs/zh/tutorial/basic/flow/what-is-flow.md | 62 ++ .../basic/node/Cloud-document-parsing.md | 91 ++- docs/zh/tutorial/basic/node/Code-execution.md | 316 +++++++-- .../tutorial/basic/node/Create-group-chat.md | 274 ++++---- docs/zh/tutorial/basic/node/Data-loading.md | 171 ++--- docs/zh/tutorial/basic/node/Data-storage.md | 185 +++--- .../tutorial/basic/node/Document-parsing.md | 184 +++--- docs/zh/tutorial/basic/node/HTTP-request.md | 169 +++++ .../basic/node/Historical-message-query.md | 164 ++--- .../basic/node/Historical-message-storage.md | 170 ++--- .../tutorial/basic/node/Image-generation.md | 131 ++++ .../tutorial/basic/node/Intent-recognition.md | 143 +++++ .../basic/node/Knowledge-retrieval.md | 139 ++++ docs/zh/tutorial/basic/node/Large-model.md | 141 ++++- docs/zh/tutorial/basic/node/Loop.md | 128 ++++ .../basic/node/Personnel-retrieval.md | 139 ++++ docs/zh/tutorial/basic/node/Selector.md | 136 ++++ .../basic/node/Spreadsheet-parsing.md | 128 ++++ docs/zh/tutorial/basic/node/Subprocess.md | 121 ++++ .../tutorial/basic/node/Text-segmentation.md | 98 ++- docs/zh/tutorial/basic/node/Tool.md | 140 ++++ .../zh/tutorial/basic/node/Variable-saving.md | 154 +++++ .../zh/tutorial/basic/node/Vector-deletion.md | 123 ++++ .../node/Vector-knowledge-base-matching.md | 146 +++++ docs/zh/tutorial/basic/node/Vector-search.md | 147 +++++ docs/zh/tutorial/basic/node/Vector-storage.md | 141 +++++ docs/zh/tutorial/basic/node/end-node.md | 109 +++- .../tutorial/basic/open-api/flow-open-api.md | 173 +++++ docs/zh/tutorial/basic/reply-node.md | 111 ++++ docs/zh/tutorial/basic/start-node.md | 103 +++ docs/zh/tutorial/basic/wait-node.md | 102 +++ .../build-a-store-knowledge-assistant.md | 110 ++++ .../complex-tasks-in-one-sentence.md | 48 ++ ...e-to-using-the-magic-approval-assistant.md | 72 ++- docs/zh/tutorial/magic-info/core-function.md | 78 ++- docs/zh/tutorial/magic-info/index.md | 78 +++ docs/zh/tutorial/magic-info/names.md | 146 +++-- .../quick-start/build-a-bot/Key concepts.md | 22 + .../quick-build-AI-translation-assistant.md | 70 ++ .../build-a-bot/quickly-build-an-agent.md | 84 +++ .../build-a-bot/tools/build-a-tool.md | 135 ++-- .../tutorial/quick-start/manage-llm/llm2.md | 56 ++ frontend/es6-template-strings/README.md | 71 +++ frontend/es6-template-strings/README.zhCN.md | 75 ++- frontend/magic-flow/docs/helper-lines.md | 383 ++++++++++- frontend/magic-flow/docs/index.md | 17 + .../src/MagicConditionEdit/index.md | 59 +- .../src/MagicExpressionWidget/index.md | 598 ++++++++++++++---- .../performance-optimizations.md | 58 +- frontend/magic-flow/src/MagicFlow/index.md | 47 +- .../provider/BaseColorProvider/README.md | 41 ++ .../magic-ui/components/MagicAvatar/README.md | 65 ++ .../magic-ui/components/MagicButton/README.md | 58 ++ .../components/MagicCheckFavor/README.md | 59 ++ .../components/MagicCollapse/README.md | 82 +++ .../components/MagicDropdown/README.md | 93 +++ .../MagicEllipseWithTooltip/README.md | 93 +++ .../magic-ui/components/MagicIcon/README.md | 58 ++ .../magic-ui/components/MagicMenu/README.md | 140 ++++ .../magic-ui/components/MagicModal/README.md | 111 ++++ .../components/MagicPageContainer/README.md | 91 +++ .../magic-ui/components/MagicSearch/README.md | 62 ++ .../components/MagicSegmented/README.md | 142 +++++ .../magic-ui/components/MagicSpin/README.md | 63 ++ .../components/MagicSplitter/README.md | 100 +++ .../components/MagicStreamContent/README.md | 57 ++ .../magic-ui/components/MagicTable/README.md | 103 +++ .../magic-ui/components/MagicTag/README.md | 53 ++ .../components/MagicUploadAction/README.md | 71 +++ .../components/base/MagicAppLoader/README.md | 64 ++ .../components/base/MagicAvatar/README.md | 65 ++ .../components/base/MagicBlock/README.md | 59 ++ .../components/base/MagicButton/README.md | 58 ++ .../components/base/MagicCheckFavor/README.md | 62 ++ .../components/base/MagicCollapse/README.md | 82 +++ .../components/base/MagicDropdown/README.md | 93 +++ .../base/MagicEllipseWithTooltip/README.md | 93 +++ .../components/base/MagicEmoji/README.md | 52 ++ .../components/base/MagicEmojiPanel/README.md | 74 +++ .../components/base/MagicEmpty/README.md | 52 ++ .../components/base/MagicEmptyFavor/README.md | 46 ++ .../components/base/MagicIcon/README.md | 57 ++ .../base/MagicImagePreview/README.md | 95 +++ .../components/base/MagicMarkmap/README.md | 87 +++ .../components/base/MagicMarpit/README.md | 103 ++- .../components/base/MagicMarpit/example.md | 56 ++ .../components/base/MagicMenu/README.md | 140 ++++ .../components/base/MagicMermaid/README.md | 94 +++ .../components/base/MagicMindmap/README.md | 167 +++-- 128 files changed, 14604 insertions(+), 953 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/README.md b/.github/ISSUE_TEMPLATE/README.md index 28f12a552..104cdd3c1 100644 --- a/.github/ISSUE_TEMPLATE/README.md +++ b/.github/ISSUE_TEMPLATE/README.md @@ -1,3 +1,101 @@ +# Template Issue di Magic + +Questa directory contiene template per le issue del progetto Magic per aiutarti a segnalare problemi e richiedere funzionalità in modo efficace. + +**🇮🇹 Utenti Italiani**: Utilizza i template qui sotto senza il suffisso `-zh`. + +## Template Disponibili + +### 🐛 Segnalazione Bug (`01-bug-report.yml`) +Utilizza questo template per segnalare bug o comportamenti inattesi in Magic. + +**Quando utilizzare:** +- Magic non funziona come previsto +- Incontri errori o crash +- Le funzionalità si comportano in modo incorretto + +### ✨ Richiesta Funzionalità (`02-feature-request.yml`) +Utilizza questo template per suggerire nuove funzionalità o miglioramenti. + +**Quando utilizzare:** +- Hai un'idea per migliorare Magic +- Hai bisogno di funzionalità che non esistono +- Vuoi suggerire miglioramenti alle funzionalità esistenti + +### 📚 Documentazione (`03-documentation.yml`) +Utilizza questo template per segnalare problemi di documentazione o suggerire miglioramenti. + +**Quando utilizzare:** +- La documentazione è mancante, poco chiara o incorretta +- Hai bisogno di esempi o tutorial migliori +- La documentazione API necessita aggiornamenti + +### ⚡ Problema di Performance (`04-performance.yml`) +Utilizza questo template per segnalare problemi di performance o suggerire ottimizzazioni. + +**Quando utilizzare:** +- Magic funziona lentamente +- Uso elevato delle risorse (CPU, memoria) +- Gli endpoint API impiegano troppo tempo a rispondere + +### 🔒 Problema di Sicurezza (`05-security.yml`) +Utilizza questo template per segnalare problemi di sicurezza non critici. + +**⚠️ IMPORTANTE:** Per vulnerabilità di sicurezza critiche, invia un'email direttamente a team@dtyq.com invece di creare un issue pubblico. + +**Quando utilizzare:** +- Header di sicurezza mancanti +- Dipendenze obsolete +- Miglioramenti delle best practice di sicurezza + +### 🔌 Problema API / Integrazione (`06-api-integration.yml`) +Utilizza questo template per segnalare problemi con API, SDK o integrazioni di terze parti. + +**Quando utilizzare:** +- Gli endpoint API non funzionano correttamente +- L'integrazione con servizi esterni fallisce +- Problemi con SDK o librerie + +### 🚀 Problema di Deployment / Installazione (`07-deployment.yml`) +Utilizza questo template per segnalare problemi con l'installazione o il deployment di Magic. + +**Quando utilizzare:** +- Il processo di installazione fallisce +- I container Docker non si avviano +- Problemi di configurazione durante l'installazione + +## Come Scegliere il Template Giusto + +1. **Inizia con il tipo di issue** - Che tipo di problema stai riscontrando? +2. **Considera il componente** - Quale parte di Magic è interessata? +3. **Verifica la gravità** - Quanto è critico il problema? + +## Prima di Creare un'Issue + +1. **Cerca issue esistenti** - Verifica se il tuo problema è già stato segnalato +2. **Leggi la documentazione** - Visita [docs.letsmagic.cn](https://docs.letsmagic.cn/en) +3. **Prova l'ultima versione** - Assicurati di utilizzare la release più recente +4. **Raccogli informazioni** - Raccogli log, messaggi di errore e dettagli dell'ambiente + +## Hai Bisogno di Aiuto? + +Se non sei sicuro di quale template utilizzare o hai bisogno di aiuto con Magic: + +- 💬 **Discussioni**: [GitHub Discussions](https://github.com/dtyq/magic/discussions) +- 📖 **Documentazione**: [docs.letsmagic.cn](https://docs.letsmagic.cn/en) | [中文文档](https://docs.letsmagic.cn/zh) +- 🌐 **Sito Web Ufficiale**: [letsmagic.ai](https://www.letsmagic.ai) +- 📧 **Supporto Enterprise**: bd@dtyq.com + +## Contributi + +Accogliamo con favore i contributi! Consulta la nostra [Guida ai Contributi](../../CONTRIBUTING.md) per ulteriori informazioni su come contribuire a Magic. + +--- + +Grazie per aiutare a migliorare Magic! 🔮 + +--- + # Magic Issue Templates This directory contains issue templates for the Magic project to help you report issues and request features effectively. @@ -92,4 +190,4 @@ We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING --- -Thank you for helping improve Magic! 🔮 \ No newline at end of file +Thank you for helping improve Magic! 🔮 diff --git a/.gitignore b/.gitignore index 047b0171e..b7bd8c213 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +TRANSLATION_CHECKLIST.md .buildpath .settings/ .project diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md index 580cb05b0..0137afd69 100644 --- a/CONTRIBUTING_CN.md +++ b/CONTRIBUTING_CN.md @@ -1,3 +1,102 @@ +# Guida ai Contributi 🎉 + +Siamo felici che tu sia interessato a contribuire a Magic - è fantastico, non vediamo l'ora di vedere cosa farai. Come startup con risorse limitate in termini di personale e finanziamenti, abbiamo grandi ambizioni di costruire le applicazioni LLM più potenti. Qualsiasi aiuto dalla community conta davvero. + +Considerando la nostra situazione attuale, dobbiamo essere agili e rilasciare velocemente, ma vogliamo anche assicurarci che contributori come te abbiano un'esperienza di contribuzione il più fluida possibile. Per questo abbiamo scritto questa guida ai contributi, con l'obiettivo di familiarizzarti con il codebase e con il modo in cui lavoriamo con i contributori, così potrai passare rapidamente alla parte divertente. + +Questa guida, come Magic stesso, è un lavoro in corso. Apprezziamo molto la tua comprensione se a volte è in ritardo rispetto al progetto reale, e accogliamo con favore qualsiasi feedback per migliorare. + +Per quanto riguarda la licenza, dedica un minuto a leggere il nostro breve [Accordo di Licenza e Contributore](./LICENSE). La community aderisce anche al [codice di condotta](https://github.com/dtyq/.github/blob/main/CODE_OF_CONDUCT.md). + +## Prima di Iniziare 🔎 + +Cerchi qualcosa da affrontare? Sfoglia i nostri [problemi adatti ai principianti](https://github.com/dtyq/magic/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) e scegline uno per iniziare! + +Hai una bella idea o una funzionalità da aggiungere? Apri una PR nel nostro [repository principale](https://github.com/dtyq/magic) e mostraci cosa hai costruito. + +Devi aggiornare una funzionalità esistente o risolvere dei bug? Apri una PR nel nostro [repository principale](https://github.com/dtyq/magic) e fai accadere la tua magia! ✨ + +Unisciti al divertimento, contribuisci e costruiamo qualcosa di straordinario insieme! 💡 + +Non dimenticare di collegare un issue esistente o aprirne uno nuovo nella descrizione della PR. + +### Segnalazione Bug 🐛 + +> [!IMPORTANTE] +> Assicurati di includere le seguenti informazioni quando invii una segnalazione di bug: + +- Un titolo chiaro e descrittivo +- Una descrizione dettagliata del bug, inclusi eventuali messaggi di errore +- Passi per riprodurre il bug +- Comportamento atteso +- **Log**, se disponibili; per problemi backend sono molto importanti, puoi trovarli nei log di docker-compose +- Screenshot o video, se applicabili 📷 + +Come determiniamo le priorità: + +| Tipo di Problema | Priorità | +| ---------------- | --------- | +| Bug in funzioni core (servizio cloud, impossibile fare il login, applicazioni non funzionanti, falle di sicurezza) | Critica | +| Bug non critici, miglioramenti di performance | Priorità Media | +| Correzioni minori (refusi, UI confusa ma funzionante) | Bassa Priorità | + +### Richieste di Funzionalità ✨ + +> [!NOTA] +> Assicurati di includere le seguenti informazioni quando invii una richiesta di funzionalità: + +- Un titolo chiaro e descrittivo +- Una descrizione dettagliata della funzionalità +- Un caso d'uso per la funzionalità +- Qualsiasi altro contesto o screenshot relativo alla richiesta di funzionalità + +Come determiniamo le priorità: + +| Tipo di Funzionalità | Priorità | +| -------------------- | --------- | +| Funzionalità contrassegnate come ad alta priorità dai membri del team | Alta Priorità | +| Richieste di funzionalità popolari dal nostro [forum di feedback della community](https://github.com/dtyq/magic/discussions/categories/feedbacks) | Priorità Media | +| Funzionalità non core e piccoli miglioramenti | Bassa Priorità | +| Funzionalità preziose ma non urgenti | Funzionalità Future | + +## Invia la tua PR 🚀 + +### Processo Pull Request + +1. Fai il fork del repository +2. Prima di redigere la PR, crea un issue per discutere le modifiche che vuoi fare +3. Crea un nuovo branch per le tue modifiche +4. Aggiungi test appropriati per le tue modifiche +5. Assicurati che il tuo codice passi i test esistenti +6. Collega l'issue relativo nella descrizione della PR, `fixes #` +7. Merge riuscito! + +### Configurazione Progetto + +#### Frontend + +Per configurare il servizio frontend, fai riferimento alla guida completa nel file `frontend/README.md`: https://github.com/dtyq/magic/blob/main/frontend/README.md. Questo documento fornisce istruzioni dettagliate per configurare correttamente l'ambiente frontend. + +#### Backend + +Per configurare il servizio backend, fai riferimento alle istruzioni nel file `backend/README.md`: https://github.com/dtyq/magic/blob/main/backend/README.md. Questo documento contiene indicazioni passo passo per avviare il backend senza problemi. + +#### Altre Note + +Ti consigliamo di leggere attentamente questo documento prima di procedere con la configurazione, poiché contiene informazioni importanti su: +- Prerequisiti e dipendenze +- Passi di installazione +- Dettagli di configurazione +- Suggerimenti comuni per la risoluzione dei problemi + +Se incontri qualsiasi problema durante la configurazione, non esitare a contattarci. + +## Ottieni Aiuto 🆘 + +Se incontri difficoltà durante il processo di contribuzione o hai problemi urgenti, sentiti libero di farci domande attraverso l'issue GitHub correlato. + +--- + # 贡献指南 很高兴你有兴趣为 Magic 做出贡献 - 这太棒了，我们迫不及待地想看看你会做些什么。作为一家人员和资金有限的创业公司，我们有宏大的抱负，致力于构建最强大的 LLM 应用程序。来自社区的任何帮助都非常重要，这是真的。 diff --git a/README_CN.md b/README_CN.md index 20706dbc3..9a4dbee7b 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,9 +1,207 @@
- README in English - 简体中文版自述文件 + README in inglese + README in cinese semplificato
-![麦吉开源产品矩阵](https://public-cdn.letsmagic.ai/static/img/super-magic-publish-header.png?v=20250819) +![Matrice di Prodotti Open Source Magic](https://public-cdn.letsmagic.ai/static/img/super-magic-publish-header.png?v=20250819) + +# 🔥 Magic - Prima Piattaforma Open Source Tutto-in-Uno per la Produttività AI 🚀 + + + +Magic mira ad aiutare imprese di tutte le dimensioni a costruire e distribuire rapidamente applicazioni AI per ottenere un aumento di produttività di 100x. ⚡️ + +## Matrice di Prodotto Magic 🧩 + +Magic è la prima **"piattaforma open source tutto-in-uno per la produttività AI"**, non un singolo prodotto AI, ma una matrice di prodotti completa con capacità ricche. + +![Matrice di Prodotti](https://public-cdn.letsmagic.ai/static/img/super-magic-open-source-projects.png?v=20250819) + +- **[Super Magic](https://github.com/dtyq/super-magic)** - Un **AI Agent general purpose** progettato per scenari di compiti complessi 🤖 +- **[Magic IM](https://github.com/dtyq/magic)** - Un sistema di messaggistica istantanea di livello enterprise che integra conversazioni con Agent AI nella comunicazione interna aziendale 💬 +- **[Magic Flow](https://github.com/dtyq/magic)** - Un potente sistema di orchestrazione di workflow AI visuale 🔁 +- **Teamshare OS** (Prossimamente) - Un sistema di ufficio collaborativo online di livello enterprise 🏢 + +Oltre ai prodotti AI sopra, abbiamo anche open-sourcizzato alcune delle infrastrutture utilizzate per costruire questi prodotti: + +- **[Agentlang](https://github.com/dtyq/agentlang)** - Un framework per Agent AI basato sul linguaggio per costruire agenti AI con linguaggio naturale (attualmente disponibile in versione Python, versione TypeScript in arrivo) 🗣️ +- **[Magic Lens](https://github.com/dtyq/magiclens)** - Uno strumento potente e flessibile di conversione da HTML a Markdown che utilizza un sistema di regole estensibile per convertire accuratamente documenti HTML complessi in formato Markdown conciso 🔍 +- **Magic Use** (Prossimamente) - Uno strumento rivoluzionario per operazioni browser specificamente progettato per Agent AI 🧭 +- **Magic Space** (Prossimamente) - Un sistema di gestione hosting contenuti statici completamente nuovo specificamente orientato agli Agent AI +- **Sandbox OS** (Prossimamente) - Un potente sistema runtime sandbox orientato agli Agent AI + +### Super Magic + +Un potente **AI Agent general purpose**, progettato specificamente per scenari di compiti complessi. Attraverso un sistema di design multi-agente e capacità di tool ricchi, Super Magic supporta capacità intelligenti come **comprensione autonoma dei task**, **pianificazione autonoma dei task**, **azione autonoma** e **correzione autonoma degli errori**. È in grado di comprendere istruzioni in linguaggio naturale, eseguire vari processi aziendali e consegnare risultati finali degli obiettivi. Come prodotto di punta della matrice di prodotti Magic, Super Magic fornisce potenti capacità di sviluppo secondario attraverso open source, permettendo alle imprese di costruire e distribuire rapidamente assistenti intelligenti che soddisfano esigenze aziendali specifiche, migliorando significativamente l'efficienza e la qualità delle decisioni. + +![Super Magic](https://public-cdn.letsmagic.ai/static/img/super-magic-buffett.gif) + +#### Alcuni Casi di Super Magic +- [Analisi delle intuizioni di investimento dell'Assemblea Azionisti 2025 di Warren Buffett](https://www.letsmagic.cn/share/777665156986277889) +- [Analisi delle azioni correlate alla mezza maratona dei robot umanoidi di Pechino](https://www.letsmagic.cn/share/774280936479625217) +- [Riassunto dei concetti core di "Thinking, Fast and Slow"](https://www.letsmagic.cn/share/777461325648195584) +- [Analisi IPO e consigli di investimento di Shanghai Auntie](https://www.letsmagic.cn/share/777604044873928705) +- [Richiesta previsione vendite SKU](https://www.letsmagic.cn/share/771022574397648897) +- Per più casi visita il [sito ufficiale](https://www.letsmagic.cn) + +### Magic Flow + +Magic Flow è un potente sistema di orchestrazione di workflow AI visuale che permette agli utenti di costruire workflow complessi di AI Agent su un canvas libero. Ha le seguenti caratteristiche core: + +- **Orchestrazione Visuale**: Interfaccia intuitiva drag-and-drop, progettare workflow AI complessi senza scrivere codice, realizzare facilmente varie combinazioni di funzionalità attraverso connessioni di nodi. +- **Libreria Componenti Ricca**: Componenti predefiniti integrati multipli, inclusi moduli di elaborazione testo, generazione immagini, esecuzione codice, ecc., soddisfacendo esigenze aziendali diversificate. +- **Supporto Modelli Completo**: Compatibile con qualsiasi modello di grandi dimensioni che segue il protocollo OpenAI API, scelta flessibile di capacità AI adatte allo scenario aziendale. +- **Capacità Integrazione Sistema**: Supporta integrazione seamless con Magic IM e altri sistemi IM di terze parti (WeChat aziendale, DingTalk, Feishu), realizzazione collaborazione cross-platform. +- **Estensione Personalizzata**: Supporta sviluppo di nodi tool personalizzati, soddisfacendo esigenze specifiche di scenari aziendali particolari. +- **Debug e Monitoraggio in Tempo Reale**: Fornisce funzioni complete di debug e monitoraggio, aiutando a identificare e risolvere rapidamente problemi nei workflow, assicurando funzionamento stabile delle applicazioni AI. + +![Magic Flow](https://public-cdn.letsmagic.ai/static/img/magic-flow.png) + +Come componente importante della matrice di prodotti Magic, Magic Flow può integrarsi seamless con altri prodotti Magic, creando un ecosistema applicativo AI di livello enterprise completo. + +![Magic Multi-Agents and Events](https://public-cdn.letsmagic.ai/static/img/super-magic-multi-agents-and-events.png?v=20250819) + +### Magic IM + +Magic IM è un sistema di dialogo AI Agent di livello enterprise, progettato specificamente per scenari di gestione conoscenza interna aziendale e customer service intelligente. Fornisce capacità di dialogo ricche, supportando dialogo multi-turno, comprensione contesto, ricerca knowledge base, ecc., permettendo alle imprese di costruire rapidamente applicazioni come customer service intelligente, knowledge assistant, ecc. + +Il sistema Magic IM ha le seguenti caratteristiche core: + +- **Gestione Knowledge Base**: Potente funzione di gestione knowledge base, supportando importazione documenti in molteplici formati, indicizzazione automatica e ricerca semantica, assicurando che le risposte AI siano basate su conoscenza aziendale reale. +- **Gestione Dialogo**: Gestione dialogo completa, supportando distinzione contenuti dialogo diversi attraverso topic, supportando contemporaneamente dialogo con AI Agent e dialogo con persone nell'organizzazione. +- **Capacità Group Chat**: Potente funzione group chat, supportando collaborazione in tempo reale multi-persona, AI intelligente partecipa al group chat e fornisce risposte immediate, promuovendo comunicazione efficiente del team e condivisione conoscenza. +- **Architettura Multi-Organizzazione**: Supporta deployment multi-organizzazione e isolamento dati organizzazione rigoroso, ogni organizzazione possiede spazio dati indipendente e permessi di accesso. +- **Sicurezza Dati**: Meccanismo rigoroso di isolamento dati e controllo accesso, gestione permessi multi-livello, salvaguardia sicurezza informazioni sensibili aziendali, assicurando che dati tra organizzazioni non si divulghino reciprocamente. + +![Magic IM](https://public-cdn.letsmagic.ai/static/img/magic-im-group-chat.png?v=20250819) + +## Teamshare OS Sistema Collaborativo Ufficio + +Teamshare OS è una piattaforma collaborativa ufficio moderna di livello enterprise, progettata specificamente per migliorare efficienza collaborazione team e gestione conoscenza. Come componente importante della matrice Magic, Teamshare integra profondamente capacità AI nelle attività ufficio quotidiane, ottenendo workflow e gestione conoscenza intelligenti. + +Teamshare OS ha le seguenti caratteristiche core: + +- **Gestione Documenti Intelligente**: Supporta editing online, collaborazione e controllo versioni di molteplici formati documento, generazione e ottimizzazione contenuti assistita da AI, rendendo gestione documenti team più efficiente. +- **Magic Table**: Potente strumento gestione dati multidimensionale, supportando tipi campo personalizzati, viste multiple e workflow automatizzati, combinato con capacità AI per ottenere elaborazione dati intelligente, soddisfacendo esigenze diversificate di gestione dati. +- **Gestione Collaborazione Progetti**: Bacheche progetto e gestione attività intuitive, supportando workflow personalizzati, combinate con analisi intelligente AI per fornire previsioni progresso progetto e suggerimenti ottimizzazione risorse. +- **Costruzione Knowledge Base**: Potente sistema consolidamento e ricerca conoscenza, strutturando automaticamente documenti interni aziendali per formare asset conoscenza aziendale sostenibili. +- **Capacità Integrazione Completa**: Integrazione seamless con matrice prodotti Magic, supportando anche collegamento con software ufficio mainstream e applicazioni aziendali, creando piattaforma lavoro unificata. + +### Magic Table 🧾 + +https://gist.github.com/user-attachments/assets/6ef46e66-292c-4a8a-8a00-a3b9fb7beec7 + +### Magic Doc 📄 + +https://gist.github.com/user-attachments/assets/7327f331-be7d-4aeb-8e19-0949adde66b2 + +## 🚀 Uso di Super Magic + +### Servizio Cloud ☁️ + +Forniamo [servizi cloud](https://www.letsmagic.ai) per [Super Magic](https://www.letsmagic.ai), [Magic IM](https://www.letsmagic.ai) e [Magic Flow](https://www.letsmagic.ai), permettendo a chiunque di iniziare a provarli e usarli senza configurazione, offrendo tutte le funzionalità della versione open source. +*Attualmente è richiesto un codice di invito per l'accesso, che può essere richiesto online e concesso per uso di prova dopo approvazione.* 🔑 + +### Magic per Imprese/Organizzazioni 🏢✨ + +Forniamo capacità e funzionalità di gestione più potenti per team e imprese. [Mandaci una email](mailto:bd@dtyq.com?subject=[GitHub]Business%20License%20Inquiry) per discutere le esigenze enterprise. + +### Edizione Community Self-Hosted 🧑‍💻 + +#### Requisiti di Sistema ⚙️ +- Docker 24.0+ +- Docker Compose 2.0+ + +#### Avviare il Sistema con Docker ▶️ + +```bash +# Clona il repository +git clone https://github.com/dtyq/magic.git +cd magic + +# Avvia il servizio in primo piano +./bin/magic.sh start +``` + +##### Altri Comandi 🛠️ + +```bash +# Avvia il servizio in background +./bin/magic.sh daemon + +# Visualizza lo stato del servizio +./bin/magic.sh status + +# Visualizza i log +./bin/magic.sh logs +``` + +##### Configurazione Variabili Ambiente + +```bash +# Configura variabili ambiente magic, deve configurare variabili ambiente di qualsiasi modello di grandi dimensioni per poter usare normalmente magic +cp .env.example .env + +# Configura variabili ambiente Super Magic, deve configurare variabili ambiente di qualsiasi modello di grandi dimensioni che supporti formato openai per poter usare normalmente +./bin/magic.sh status +cp config/.env_super_magic.example .env_super_magic +``` + +##### Accesso ai Servizi +- Servizio API: http://localhost:9501 +- Applicazione Web: http://localhost:8080 + - Account `13812345678`: password `letsmagic.ai` + - Account `13912345678`: password `letsmagic.ai` +- Interfaccia di gestione RabbitMQ: http://localhost:15672 + - Username: admin + - Password: magic123456 + +## 📚 Sito Ufficiale e Documentazione + +Sito ufficiale [https://www.letsmagic.ai](https://www.letsmagic.ai) +Documentazione [https://docs.letsmagic.ai/zh](https://docs.letsmagic.ai/zh) + +## 🤝 Contributi + +Per chi vuole contribuire codice, consulta la nostra [Guida ai Contributi](https://github.com/dtyq/magic/blob/master/CONTRIBUTING_CN.md). +Inoltre, considera di supportare Magic attraverso social media, eventi e conferenze - lo sviluppo di Magic non può fare a meno del tuo supporto. + +## 🔒 Vulnerabilità di Sicurezza + +Se scopri vulnerabilità di sicurezza in Magic, invia un'email al team ufficiale Magic all'indirizzo [team@dtyq.com](mailto:team@dtyq.com), tutte le vulnerabilità di sicurezza saranno risolte tempestivamente. + +## 📄 Licenza + +Questo repository segue il protocollo open source [Magic Open Source License](LICENSE), questa licenza è essenzialmente Apache 2.0 ma con alcune restrizioni aggiuntive. + +## 🙏 Ringraziamenti + +Grazie a tutti gli sviluppatori che hanno contribuito a Magic! + +[![Grafico Cronologia Stelle](https://api.star-history.com/svg?repos=dtyq/magic&type=Date)](https://star-history.com/#dtyq/magic&Date) + +--- # 🔥 麦吉 - 首个开源一站式 AI 生产力平台 @@ -163,15 +361,11 @@ cd magic # 配置magic 环境变量, 必须配置任意一种大模型的环境变量才可正常使用magic cp .env.example .env - # 配置超级麦吉 环境变量,必须配置任意一种支持openai 格式的大模型环境变量, 才可正常使用使用 ./bin/magic.sh status cp config/.env_super_magic.example .env_super_magic - ``` - - ##### 访问服务 - API 服务: http://localhost:9501 - Web 应用: http://localhost:8080 diff --git a/backend/code-executor/examples/README.md b/backend/code-executor/examples/README.md index c862a8828..8a7f7974a 100644 --- a/backend/code-executor/examples/README.md +++ b/backend/code-executor/examples/README.md @@ -1,3 +1,84 @@ +# Esempi di Utilizzo dell'Esecutore di Codice + +Questa directory contiene esempi di utilizzo dell'esecutore di codice, che aiutano a comprendere come integrare e utilizzare la funzionalità di esecuzione del codice nei progetti reali. + +## Spiegazione dei File di Esempio + +- `aliyun_executor_config.example.php` - File di esempio di configurazione, prima dell'uso deve essere copiato come `aliyun_executor_config.php` e compilato con la configurazione effettiva +- `aliyun_executor_example.php` - Esempio di utilizzo dell'esecutore di codice di Alibaba Cloud Function Compute + +## Passi di Utilizzo + +### 1. Preparazione del File di Configurazione + +```bash +# Copiare il file di esempio di configurazione +cp aliyun_executor_config.example.php aliyun_executor_config.php + +# Modificare il file di configurazione, inserire le informazioni del proprio account Alibaba Cloud +vim aliyun_executor_config.php +``` + +### 2. Eseguire l'Esempio + +```bash +# Eseguire l'esempio dell'esecutore di codice Alibaba Cloud +php aliyun_executor_example.php +``` + +## Spiegazione dell'Output di Esempio + +Dopo l'esecuzione dell'esempio, si vedrà un output simile al seguente: + +``` +=== Esempio Esecutore Alibaba Cloud === + +Creazione del client runtime in corso... +Creazione dell'esecutore in corso... +Inizializzazione dell'ambiente di esecuzione in corso... +Inizializzazione dell'ambiente di esecuzione completata + +Esecuzione del codice in corso... + +Esecuzione completata! +------------------------------ +Output di esecuzione: +Risultato del calcolo: 10 + 7 = 17 + +Tempo di esecuzione: 123ms +Tempo effettivo: 1034.56ms +Risultato di esecuzione: +``` + +```json +{ + "sum": 17, + "a": 10, + "b": 7, + "timestamp": 1679876543 +} +------------------------------ + +Eseguire test delle prestazioni? (y/n): +``` + +## Note Importanti + +1. L'utilizzo del servizio Alibaba Cloud Function Compute richiede un account Alibaba Cloud valido e una configurazione corretta +2. L'esecuzione del codice potrebbe generare costi, si prega di controllare l'utilizzo delle risorse +3. Si consiglia di verificare prima in ambiente di test prima di utilizzare in produzione + +## Risoluzione dei Problemi + +In caso di problemi, verificare: + +1. Se le informazioni nel file di configurazione sono corrette +2. Se l'account Alibaba Cloud ha autorizzazioni sufficienti +3. Se il servizio Function Compute è stato attivato +4. Se la connessione di rete è normale + +--- + # 代码执行器使用示例 本目录包含了代码执行器的使用示例，帮助您理解如何在实际项目中集成和使用代码执行功能。 @@ -48,6 +129,9 @@ php aliyun_executor_example.php 执行耗时: 123ms 实际耗时: 1034.56ms 执行结果: +``` + +```json { "sum": 17, "a": 10, @@ -56,7 +140,7 @@ php aliyun_executor_example.php } ------------------------------ -是否进行性能测试? (y/n): +是否进行性能测试? (y/n): ``` ## 注意事项 @@ -72,4 +156,4 @@ php aliyun_executor_example.php 1. 配置文件中的信息是否正确 2. 阿里云账号是否有足够的权限 3. 函数计算服务是否已开通 -4. 网络连接是否正常 \ No newline at end of file +4. 网络连接是否正常 diff --git a/backend/magic-gateway/README.md b/backend/magic-gateway/README.md index a7c439592..4169091e3 100644 --- a/backend/magic-gateway/README.md +++ b/backend/magic-gateway/README.md @@ -1,3 +1,504 @@ +# Servizio API Gateway in Go 🏰 + +Questo è un servizio API gateway ad alte prestazioni per container Docker, implementato in linguaggio Go, che può gestire in modo sicuro le variabili d'ambiente e fornire token di accesso temporanei. + +**Nota importante:** Questo gateway supporta solo la sostituzione del contenuto degli header e del dominio URL, non supporta la sostituzione del contenuto del body. + +## 🚀 Caratteristiche Principali + +- **⚡ Alte Prestazioni**: Implementato in Go, con miglioramenti significativi delle prestazioni rispetto alla versione Python +- **🔐 Servizio di Autenticazione**: Genera token di accesso temporanei per i container +- **🛡️ Protezione delle Variabili d'Ambiente**: I container non possono ottenere direttamente i valori delle variabili d'ambiente, possono solo usarli indirettamente tramite proxy API +- **🔗 Supporto Multi-Servizio**: Può supportare contemporaneamente più servizi API (come OpenAI, DeepSeek, Magic, ecc.) +- **🛤️ Routing per Nome Variabile d'Ambiente**: Accesso diretto ai servizi corrispondenti tramite nome della variabile d'ambiente +- **🔄 Proxy API**: Sostituzione automatica dei riferimenti alle variabili d'ambiente nelle richieste +- **📝 Supporto Formati Multipli di Riferimento alle Variabili**: `env:VAR`, `${VAR}`, `$VAR`, `OPENAI_*`, ecc. +- **🌍 Distribuzione Multi-Ambiente**: Supporta tre ambienti indipendenti: test, pre-release e produzione + +## 📁 Struttura del Progetto + +``` +magic-gateway/ +├── main.go # Punto di ingresso principale del programma +├── .env # File di configurazione delle variabili d'ambiente +├── README.md # Documentazione del progetto +├── deploy.sh # Script di distribuzione multi-ambiente +├── docker-compose.yml # Configurazione Docker Compose +├── Dockerfile # File di costruzione Docker +├── config/ # Directory di configurazione multi-ambiente +│ ├── test/ # Configurazione ambiente di test +│ ├── pre/ # Configurazione ambiente pre-release +│ └── prod/ # Configurazione ambiente produzione +├── docs/ # Directory documentazione +│ └── multi-environment-deployment.md # Guida dettagliata distribuzione multi-ambiente +├── tests/ # Directory test unitari e funzionali +│ ├── auth_test_client.go # Client di test interfaccia autenticazione +│ ├── auth_key_test.go # Test validazione API Key +│ └── test_api_key.go # Test funzionalità API Key +└── test_client/ # Strumenti client di test + └── test_client.go # Client di test generico +``` + +## 🏁 Avvio Rapido + +### 📋 Prerequisiti + +- Go 1.18+ (per costruzione locale) +- Docker & Docker Compose (per distribuzione containerizzata) + +### 🚀 Avvio con Script + +```bash +# Rendere eseguibile lo script di avvio del servizio +chmod +x start.sh + +# Avviare il servizio +./start.sh +``` + +### 🐳 Avvio con Docker Compose + +```bash +# Avviare il servizio +docker-compose up -d + +# Visualizzare i log +docker-compose logs -f +``` + +### 🌍 Distribuzione Multi-Ambiente + +Il gateway API supporta tre ambienti indipendenti: test, pre-release e produzione, ciascuno con configurazioni e porte diverse: + +```bash +# Prima assicurarsi che lo script di distribuzione sia eseguibile +chmod +x deploy.sh + +# Avviare ambiente di test (porta 8001) +./deploy.sh test start + +# Avviare ambiente pre-release (porta 8002) +./deploy.sh pre start + +# Avviare ambiente produzione (porta 8003) +./deploy.sh prod start + +# Avviare tutti gli ambienti contemporaneamente +./deploy.sh all start + +# Visualizzare log dell'ambiente specifico +./deploy.sh test logs + +# Verificare stato dell'ambiente +./deploy.sh pre status + +# Fermare ambiente specifico +./deploy.sh prod stop + +# Riavviare ambiente specifico +./deploy.sh test restart +``` + +Lo script di distribuzione crea automaticamente directory e file di configurazione per ciascun ambiente. Le configurazioni di ciascun ambiente sono memorizzate nel file `config//.env`, che può essere modificato secondo necessità. + +**Porte di accesso ambiente:** +- Ambiente test: http://localhost:8001 +- Ambiente pre-release: http://localhost:8002 +- Ambiente produzione: http://localhost:8003 + +Per informazioni più dettagliate sulla distribuzione multi-ambiente, fare riferimento alla [Guida alla Distribuzione Multi-Ambiente](docs/multi-environment-deployment.md). + +## ⚙️ Spiegazione Configurazione + +### 🔧 Variabili d'Ambiente + +Nel file `.env` configurare le seguenti variabili d'ambiente: + +``` +# Configurazioni Generali +JWT_SECRET=your-secret-key-change-me +API_GATEWAY_VERSION=1.0.0 +DEFAULT_API_URL=https://api.default-service.com +MAGIC_GATEWAY_API_KEY=your-gateway-api-key-here + +# Configurazioni Servizio OpenAI +OPENAI_API_KEY=sk-xxxx +OPENAI_API_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-4 + +# Configurazioni Servizio Magic +MAGIC_API_KEY=xxx +MAGIC_API_BASE_URL=https://api.magic.com/v1 +MAGIC_MODEL=gpt-4o-global + +# Configurazioni Servizio DeepSeek +DEEPSEEK_API_KEY=xxxxx +DEEPSEEK_API_BASE_URL=https://api.deepseek.com/v1 +DEEPSEEK_MODEL=deepseek-coder + +# Configurazioni Servizio Azure OpenAI +AZURE_OPENAI_EMBEDDING_API_KEY=xxxx +AZURE_OPENAI_EMBEDDING_ENDPOINT=https://example.openai.azure.com/ +AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-large +AZURE_OPENAI_EMBEDDING_DEPLOYMENT=example-text-embedding +AZURE_OPENAI_EMBEDDING_API_VERSION=2023-05-15 +``` + +**⚠️ Importante:** `MAGIC_GATEWAY_API_KEY` è una credenziale di sicurezza chiave, utilizzata solo per l'autenticazione dell'interfaccia `/auth`. Solo quando si ottiene il token è necessario fornire questa chiave API, le altre richieste dopo aver ottenuto il token utilizzano il token ottenuto per l'autenticazione e non necessitano più di fornire questa chiave API. + +### 📦 Variabili d'Ambiente Container + +Nel container, utilizzare gli stessi nomi di variabili d'ambiente, ma senza valori effettivi. Ad esempio nel file `.env` del container: + +``` +OPENAI_API_KEY="OPENAI_API_KEY" +OPENAI_API_BASE_URL="OPENAI_API_BASE_URL" +OPENAI_MODEL="OPENAI_MODEL" + +MAGIC_API_KEY="MAGIC_API_KEY" +MAGIC_API_BASE_URL="MAGIC_API_BASE_URL" +MAGIC_MODEL="MAGIC_MODEL" +``` + +## 📖 Spiegazione Utilizzo API + +### 1. 🏷️ Ottenere Token Temporaneo + +**⚠️ Suggerimento Importante:** +1. Le richieste per ottenere token temporaneo possono essere effettuate **solo** localmente dall'host (localhost/127.0.0.1), non possono essere effettuate dai container. Questo è progettato per motivi di sicurezza. +2. Quando si ottiene il token, **è necessario** fornire l'header di richiesta `X-Gateway-API-Key` valido, il cui valore deve corrispondere a `MAGIC_GATEWAY_API_KEY` nelle variabili d'ambiente. + +```bash +curl -X POST http://localhost:8000/auth \ + -H "magic-user-id: your-user-id" \ + -H "magic-organization-code: your-organization-code" \ + -H "X-Gateway-API-Key: your-gateway-api-key-here" +``` + +Esempio risposta: +```json +{ + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "header": "Magic-Authorization", + "example": "Magic-Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +Il token temporaneo ora è **permanentemente valido**, senza limite di tempo di scadenza. È sufficiente ottenerlo una volta e può essere utilizzato a lungo termine. Durante l'esecuzione del container, dovrebbe essere iniettato dalle variabili d'ambiente dell'host nel container al momento dell'avvio. Si noti di utilizzare l'header `Magic-Authorization` invece del `Authorization` standard. + +### 2. 🔍 Query Variabili d'Ambiente Disponibili + +```bash +# Ottenere tutti i nomi delle variabili d'ambiente consentite +curl http://host.docker.internal:8000/env \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" + +# Verificare se una variabile d'ambiente specifica è disponibile +curl "http://host.docker.internal:8000/env?vars=OPENAI_API_KEY,OPENAI_MODEL" \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" +``` + +Esempio risposta: +```json +{ + "available_vars": ["OPENAI_API_KEY", "OPENAI_MODEL", "OPENAI_API_BASE_URL", "MAGIC_API_KEY", "MAGIC_MODEL", "API_GATEWAY_VERSION"], + "message": "Non è consentito ottenere direttamente i valori delle variabili d'ambiente, utilizzare il proxy API per utilizzare queste variabili" +} +``` + +### 3. 🔗 Query Servizi Disponibili + +```bash +curl http://localhost:8000/services \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" +``` + +Esempio risposta: +```json +{ + "available_services": [ + { + "name": "OPENAI", + "base_url": "api.openai.com", + "default_model": "gpt-4" + }, + { + "name": "MAGIC", + "base_url": "api.magic.com", + "default_model": "gpt-4o-global" + }, + { + "name": "DEEPSEEK", + "base_url": "api.deepseek.com", + "default_model": "deepseek-coder" + } + ], + "message": "È possibile utilizzare il proxy API per utilizzare questi servizi, formato: /{service}/path o utilizzare riferimenti env:" +} +``` + +### 4. 🔄 Utilizzo Proxy API e Sostituzione Variabili d'Ambiente + +Esistono molteplici modi per chiamare diversi servizi: + +#### 📍 Metodo 1: Accesso diretto tramite nome variabile d'ambiente (consigliato) + +```bash +# Accesso diretto tramite nome variabile d'ambiente +curl -X POST http://host.docker.internal:8000/OPENAI_API_BASE_URL/v1/chat/completions \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-4", + "messages": [ + {"role": "user", "content": "Hello!"} + ] + }' + +# È anche possibile utilizzare direttamente il nome della variabile d'ambiente come valore (quando la stringa corrisponde completamente) +curl -X POST http://host.docker.internal:8000/OPENAI_API_BASE_URL/v1/chat/completions \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "OPENAI_MODEL", + "messages": [ + {"role": "user", "content": "Hello!"} + ] + }' + +# Utilizzo servizio Magic +curl -X POST http://host.docker.internal:8000/MAGIC_API_BASE_URL/v1/chat/completions \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "MAGIC_MODEL", + "messages": [ + {"role": "user", "content": "Hello!"} + ] + }' +``` + +#### 📍 Metodo 2: Accesso tramite nome servizio + +```bash +# Chiamata servizio OpenAI +curl -X POST http://host.docker.internal:8000/openai/v1/chat/completions \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "env:OPENAI_MODEL", + "messages": [ + {"role": "user", "content": "Hello!"} + ] + }' + +# Chiamata servizio Magic +curl -X POST http://host.docker.internal:8000/magic/v1/chat/completions \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "env:MAGIC_MODEL", + "messages": [ + {"role": "user", "content": "Hello!"} + ] + }' +``` + +#### 📍 Metodo 3: Utilizzo parametri query per specificare servizio + +```bash +curl -X POST "http://host.docker.internal:8000/v1/chat/completions?service=deepseek" \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "env:DEEPSEEK_MODEL", + "messages": [ + {"role": "user", "content": "Hello!"} + ] + }' +``` + +#### 📍 Metodo 4: Utilizzo riferimenti variabili d'ambiente + +```bash +curl -X POST http://host.docker.internal:8000/v1/chat/completions \ + -H "Magic-Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "env:OPENAI_MODEL", + "api_base": "${OPENAI_API_BASE_URL}", + "messages": [ + {"role": "user", "content": "Hello!"} + ] + }' +``` + +## 🐳 Integrazione Container Docker + +Poiché esistono limitazioni di sicurezza nei container Docker, non è possibile ottenere direttamente token temporanei. Seguire i seguenti passaggi per ottenere il token dall'host e iniettarli nel container: + +### 1. 🏠 Ottenere Token Temporaneo dall'Host + +#### 🔸 Modalità Ambiente Singolo + +```bash +# Eseguire sull'host +USER_ID="your-user-id" +GATEWAY_API_KEY="your-gateway-api-key" + +# Ottenere token temporaneo (può essere eseguito solo localmente) +TOKEN=$(curl -s -X POST "http://localhost:8000/auth" \ + -H "X-USER-ID: $USER_ID" \ + -H "X-Gateway-API-Key: $GATEWAY_API_KEY" | jq -r '.token') + +echo "Token ottenuto: $TOKEN" +``` + +#### 🔸 Modalità Multi-Ambiente + +```bash +# Eseguire sull'host - specificare ambiente (test, pre, prod) +ENV="test" # Valori possibili: test, pre, prod +USER_ID="your-user-id" + +# Selezionare porta e chiave API in base all'ambiente +case $ENV in + test) + PORT=8001 + GATEWAY_API_KEY="test-gateway-api-key" + ;; + pre) + PORT=8002 + GATEWAY_API_KEY="pre-gateway-api-key" + ;; + prod) + PORT=8003 + GATEWAY_API_KEY="prod-gateway-api-key" + ;; +esac + +# Ottenere token temporaneo dell'ambiente specificato +TOKEN=$(curl -s -X POST "http://localhost:$PORT/auth" \ + -H "X-USER-ID: $USER_ID" \ + -H "X-Gateway-API-Key: $GATEWAY_API_KEY" | jq -r '.token') + +echo "Token $ENV ottenuto: $TOKEN" +``` + +### 2. 🚀 Avvio Container con Iniezione Token + +#### 🔸 Modalità Ambiente Singolo + +```bash +# Utilizzare il token ottenuto per avviare il container +docker run -e API_TOKEN="$TOKEN" \ + -e API_GATEWAY_URL="http://host.docker.internal:8000" \ + your-image +``` + +#### 🔸 Modalità Multi-Ambiente + +```bash +# Utilizzare il token ottenuto per avviare il container, specificando l'ambiente +docker run -e API_TOKEN="$TOKEN" \ + -e API_GATEWAY_URL="http://host.docker.internal:$PORT" \ + -e API_GATEWAY_ENV="$ENV" \ + your-image +``` + +### 3. 🔧 Utilizzo Token Iniettato nel Container + +```bash +# L'applicazione nel container può ottenere il token dalle variabili d'ambiente +TOKEN=$API_TOKEN +GATEWAY_URL=$API_GATEWAY_URL + +# Query servizi disponibili +curl -s "$GATEWAY_URL/services" \ + -H "Magic-Authorization: Bearer $TOKEN" +``` + +### 4. 🐳 Configurazione Multi-Ambiente con Docker Compose + +È possibile configurare i container dell'applicazione nel file docker-compose.yml per connettersi al gateway API di un ambiente specifico: + +```yaml +version: '3' + +services: + your-app: + image: your-app-image + environment: + - API_TOKEN=${API_TOKEN} + - API_GATEWAY_URL=http://host.docker.internal:${PORT:-8000} + - API_GATEWAY_ENV=${ENV:-dev} + extra_hosts: + - "host.docker.internal:host-gateway" +``` + +Poi avviare il container utilizzando le variabili d'ambiente: + +```bash +# Iniettare variabili d'ambiente per avviare il container dell'applicazione +ENV=test PORT=8001 API_TOKEN=$TOKEN docker-compose up -d +``` + +## 🔒 Caratteristiche di Sicurezza + +1. **🛡️ Protezione Variabili d'Ambiente**: I container non possono ottenere direttamente i valori delle variabili d'ambiente dell'host, possono solo utilizzarli indirettamente tramite richieste proxy API +2. **🔄 Sostituzione Variabili d'Ambiente**: Il gateway API sostituisce automaticamente i riferimenti alle variabili d'ambiente nelle richieste, il container non ha bisogno di conoscere i valori effettivi +3. **🏷️ Header di Autenticazione Personalizzati**: Utilizza l'header Magic-Authorization per evitare conflitti con l'Authorization di altri servizi +4. **🔐 Isolamento Multi-Servizio**: Le chiavi API di ciascun servizio sono gestite dal gateway e non vengono divulgate ai container +5. **⏰ Token Temporanei**: Tutte le richieste richiedono un token di autenticazione valido con limite di tempo +6. **📦 Isolamento Container**: Ogni container utilizza un token indipendente e non può accedere ai token di altri container +7. **🔑 Chiave API Gateway**: L'ottenimento del token richiede una chiave API del gateway valida (`X-Gateway-API-Key`), aggiungendo un ulteriore livello di sicurezza + +## ⚡ Confronto Prestazioni + +Rispetto alla versione Python, la versione Go del gateway API ha i seguenti vantaggi prestazionali: + +1. **💾 Minor Occupazione Memoria**: La versione Go generalmente occupa meno memoria rispetto alla versione Python +2. **🚀 Maggiore Capacità Elaborazione Concorrente**: Il modello di concorrenza di Go gli permette di gestire più efficacemente un gran numero di richieste +3. **⚡ Tempo di Avvio Più Rapido**: Go viene compilato in un singolo file eseguibile, con tempi di avvio più rapidi +4. **🔥 Latenza Ridotta**: La latenza di elaborazione delle richieste è significativamente ridotta + +## 🏗️ Istruzioni di Costruzione + +Se è necessario costruire manualmente: + +```bash +# Ottenere dipendenze +go mod tidy + +# Costruire file eseguibile +go build -o api-gateway +``` + +## 🛡️ Suggerimenti di Sicurezza + +1. Cambiare `JWT_SECRET` in ambiente di produzione +2. Aggiungere un livello proxy HTTPS quando necessario +3. Limitare i container autorizzati ad accedere +4. Ruotare regolarmente le chiavi API + +## 🔄 Funzionalità Sostituzione Variabili d'Ambiente + +Il gateway API fornisce una potente funzionalità di sostituzione delle variabili d'ambiente che può sostituire i riferimenti alle variabili d'ambiente in diverse posizioni: + +1. **📝 Sostituzione Corpo Richiesta** - Sostituisce i riferimenti alle variabili d'ambiente nel corpo JSON della richiesta nei seguenti formati: + - Corrispondenza completa nome variabile d'ambiente: `"model": "OPENAI_MODEL"` + - Prefisso `env:`: `"model": "env:OPENAI_MODEL"` + - Formato `${VAR}`: `"url": "https://example.com/${SERVICE_URL}"` + - Formato `$VAR`: `"key": "$OPENAI_API_KEY"` + +2. **🏷️ Sostituzione Header Richiesta** - Sostituisce i riferimenti alle variabili d'ambiente negli header personalizzati della richiesta + +3. **🛤️ Sostituzione Percorso URL** - Utilizza le variabili d'ambiente come prefisso del percorso URL: `/OPENAI_API_BASE_URL/v1/chat/completions` + +Questo permette ai container di utilizzare in sicurezza le variabili d'ambiente senza conoscerne i valori effettivi. Il gateway API rileva e sostituisce automaticamente i riferimenti alle variabili d'ambiente nelle richieste, e tutte le sostituzioni vengono completate lato proxy, garantendo che le informazioni sensibili non vengano esposte ai container. + +--- + # Go 版 API 网关服务 这是一个用于 Docker 容器的高性能 API 网关服务，使用 Go 语言实现，可以安全地管理环境变量并提供临时访问令牌。 diff --git a/backend/magic-gateway/README_HEADERS.md b/backend/magic-gateway/README_HEADERS.md index 9c32c38da..c678581c2 100644 --- a/backend/magic-gateway/README_HEADERS.md +++ b/backend/magic-gateway/README_HEADERS.md @@ -1,3 +1,107 @@ +# Funzionalità di Passthrough degli Header di Magic Gateway + +## Panoramica + +Magic Gateway ora supporta il passthrough degli header `magic-user-id` e `magic-organization-code` a tutte le richieste API proxy degli agenti. + +## Header Supportati + +### magic-user-id +- **Descrizione**: Identificatore univoco dell'utente +- **Tipo**: String +- **Esempio**: `magic-user-id: user123` + +### magic-organization-code +- **Descrizione**: Identificatore del codice organizzazione +- **Tipo**: String +- **Esempio**: `magic-organization-code: org456` + +## Metodi di Utilizzo + +### 1. Impostazione degli Header durante l'Autenticazione + +Durante la chiamata all'endpoint `/auth`, è possibile impostare questi header: + +```bash +curl -X POST http://localhost:8000/auth \ + -H "X-Gateway-API-Key: your-api-key" \ + -H "magic-user-id: user123" \ + -H "magic-organization-code: org456" +``` + +### 2. Passthrough durante le Richieste API Proxy + +Durante le richieste API proxy attraverso il gateway, questi header vengono automaticamente passati al servizio di destinazione: + +```bash +curl -X POST http://localhost:8000/openai/v1/chat/completions \ + -H "Authorization: Bearer your-token" \ + -H "magic-user-id: user123" \ + -H "magic-organization-code: org456" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-3.5-turbo", + "messages": [{"role": "user", "content": "Hello"}] + }' +``` + +### 3. Compatibilità + +Per mantenere la compatibilità all'indietro, il gateway supporta anche i seguenti header: + +- `X-USER-ID` - Se `magic-user-id` non esiste, verrà utilizzato questo valore +- `X-Container-ID` - Utilizzato nelle richieste di lista servizi + +## Registrazione dei Log + +Quando la modalità debug è abilitata, il gateway registra i dettagli del passthrough degli header: + +``` +Passthrough magic-user-id: user123 +Passthrough magic-organization-code: org456 +``` + +## Ricezione del Servizio di Destinazione + +Il servizio API di destinazione riceverà la richiesta contenente questi header: + +``` +magic-user-id: user123 +magic-organization-code: org456 +``` + +## Note di Attenzione + +1. I nomi degli header sono case-sensitive +2. Se il valore dell'header è vuoto, non verrà passato +3. Questi header non vengono filtrati dalla funzione `shouldSkipHeader` +4. Supporta tutti gli endpoint API degli agenti + +## Test + +È possibile testare la funzionalità utilizzando i seguenti comandi: + +```bash +# Avvio del servizio gateway +go run main.go + +# Test autenticazione +curl -X POST http://localhost:8000/auth \ + -H "X-Gateway-API-Key: your-api-key" \ + -H "magic-user-id: test-user" \ + -H "magic-organization-code: test-org" + +# Test richiesta proxy +curl -X POST http://localhost:8000/openai/v1/chat/completions \ + -H "Authorization: Bearer your-token" \ + -H "magic-user-id: test-user" \ + -H "magic-organization-code: test-org" \ + -H "Content-Type: application/json" \ + -d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello"}]}' +``` + +--- + # Magic Gateway Header 透传功能 ## 概述 diff --git a/backend/magic-gateway/README_JWT_SECURITY.md b/backend/magic-gateway/README_JWT_SECURITY.md index 80f399729..851b0e366 100644 --- a/backend/magic-gateway/README_JWT_SECURITY.md +++ b/backend/magic-gateway/README_JWT_SECURITY.md @@ -1,3 +1,215 @@ +# Spiegazione del Meccanismo di Sicurezza JWT + +## Panoramica + +Questo progetto ha implementato un meccanismo di sicurezza JWT avanzato, realizzando un'autenticazione completamente stateless, **rimuovendo completamente la dipendenza da Redis e cache in memoria**. + +## Caratteristiche Principali + +### 1. Gestione Unificata delle Chiavi +- La chiave JWT viene ottenuta dalla variabile d'ambiente `MAGIC_GATEWAY_API_KEY` +- Semplifica la gestione delle chiavi, richiede solo l'impostazione di una variabile d'ambiente +- Genera automaticamente un identificatore di versione della chiave per il rilevamento della rotazione delle chiavi + +### 2. Claims JWT Avanzati +```go +type JWTClaims struct { + jwt.RegisteredClaims + ContainerID string `json:"container_id"` + MagicUserID string `json:"magic_user_id,omitempty"` + MagicOrganizationCode string `json:"magic_organization_code,omitempty"` + TokenVersion int64 `json:"token_version"` // Versione del token + CreatedAt int64 `json:"created_at"` // Ora di creazione + KeyID string `json:"kid,omitempty"` // Identificatore versione chiave + Nonce string `json:"nonce,omitempty"` // Protezione anti-replay + Scope string `json:"scope,omitempty"` // Ambito delle autorizzazioni +} +``` + +### 3. Meccanismo di Verifica della Sicurezza +- **Verifica della versione della chiave**: Garantisce che il token utilizzi la versione corretta della chiave +- **Verifica dell'ambito delle autorizzazioni**: Limita l'ambito di utilizzo del token +- **Meccanismo di revoca globale**: Supporta la revoca di tutti i token +- **Protezione anti-replay**: Ogni token contiene un numero casuale univoco + +### 4. Autenticazione Completamente Stateless +- **Senza Redis**: Rimossa completamente la dipendenza da Redis +- **Senza cache in memoria**: Rimossa tutta la logica di storage in memoria +- **JWT self-contained**: Il JWT stesso contiene tutte le informazioni necessarie +- **Supporta scalabilità orizzontale**: Il servizio può essere distribuito completamente stateless + +## Configurazione delle Variabili d'Ambiente + +```bash +# Deve essere impostata, utilizzata per la firma JWT e la verifica della chiave API +export MAGIC_GATEWAY_API_KEY="your-strong-secret-key-at-least-32-characters" + +# Opzionale: modalità debug +export MAGIC_GATEWAY_DEBUG="true" +``` + +## Endpoint API + +### 1. Ottenere il Token +```bash +curl -X POST http://localhost:8000/auth \ + -H "X-Gateway-API-Key: your-strong-secret-key-at-least-32-characters" \ + -H "X-USER-ID: user123" \ + -H "magic-user-id: magic123" \ + -H "magic-organization-code: org123" +``` + +Esempio di risposta: +```json +{ + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "header": "Magic-Authorization", + "example": "Magic-Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "note": "Assicurati di aggiungere il prefisso Bearer quando utilizzi il token, altrimenti il gateway lo aggiungerà automaticamente", + "security": "Il token include protezione anti-replay e controllo versione chiave" +} +``` + +### 2. Revocare Tutti i Token +```bash +curl -X POST http://localhost:8000/revoke-all \ + -H "Magic-Authorization: Bearer your-token-here" +``` + +### 3. Visualizzare lo Stato +```bash +curl http://localhost:8000/status +``` + +Esempio di risposta: +```json +{ + "status": "ok", + "version": "1.0.0", + "auth_mode": "stateless_jwt", + "token_validity": "30天", + "env_vars_available": ["OPENAI_API_BASE_URL", "MAGIC_API_KEY", ...], + "services_available": ["OPENAI", "MAGIC", "DEEPSEEK"], + "current_token_version": 5, + "global_revoke_timestamp": 0, + "jwt_key_id": "a1b2c3d4", + "jwt_algorithm": "HS256" +} +``` + +## Vantaggi di Sicurezza + +1. **Gestione unificata delle chiavi**: Necessario gestire solo una chiave +2. **Controllo versione chiave**: Può rilevare se la chiave è stata modificata +3. **Protezione anti-replay**: Ogni token ha un numero casuale univoco +4. **Controllo ambito autorizzazioni**: Limita l'ambito di utilizzo del token +5. **Verifica algoritmo**: Garantisce l'uso dell'algoritmo di firma corretto +6. **Revoca globale**: Supporta la revoca una tantum di tutti i token +7. **Completamente stateless**: Nessuna dipendenza da storage esterno + +## Utilizzo del Token + +```bash +# Utilizzare il token per accedere all'API +curl http://localhost:8000/env \ + -H "Magic-Authorization: Bearer your-token-here" + +# O utilizzare l'header Authorization standard +curl http://localhost:8000/env \ + -H "Authorization: Bearer your-token-here" +``` + +## Note di Attenzione + +1. **Robustezza della chiave**: Si consiglia di utilizzare una chiave forte di almeno 32 caratteri +2. **Rotazione delle chiavi**: Il sistema rileva il tempo di utilizzo della chiave, si consiglia la rotazione periodica +3. **Scadenza del token**: Il token ha validità di 30 giorni, scade automaticamente +4. **Meccanismo di revoca**: Utilizzare l'endpoint `/revoke-all` per revocare tutti i token +5. **Modalità debug**: Impostare `MAGIC_GATEWAY_DEBUG=true` per visualizzare i log dettagliati +6. **Distribuzione stateless**: Il servizio può essere distribuito completamente stateless, senza Redis + +## Guida alla Migrazione + +### Migrazione dalla Versione Precedente + +1. **Impostare le variabili d'ambiente**: + ```bash + export MAGIC_GATEWAY_API_KEY="your-strong-secret-key" + ``` + +2. **Rimuovere le vecchie configurazioni**: + - Non più necessaria la variabile d'ambiente `JWT_SECRET` + - Non più necessarie le configurazioni Redis + - Non più necessarie le dipendenze Redis + +3. **Aggiornare le dipendenze**: + ```bash + # Rimuovere le dipendenze Redis + go mod tidy + ``` + +4. **Aggiornare i client**: + - Il formato del token rimane invariato + - La logica di verifica rimane invariata + - Aggiunte nuove informazioni di sicurezza nell'header + +### Verifica della Migrazione + +```bash +# 1. Ottenere un nuovo token +curl -X POST http://localhost:8000/auth \ + -H "X-Gateway-API-Key: your-strong-secret-key-at-least-32-characters" \ + -H "X-USER-ID: test-user" + +# 2. Utilizzare il token per accedere all'API +curl http://localhost:8000/status \ + -H "Magic-Authorization: Bearer your-token" + +# 3. Verificare le informazioni di stato +curl http://localhost:8000/status +``` + +## Risoluzione dei Problemi + +### Problemi Comuni + +1. **Errore chiave**: + ``` + Errore: È necessario impostare la variabile d'ambiente MAGIC_GATEWAY_API_KEY + ``` + Soluzione: Impostare la variabile d'ambiente corretta + +2. **Verifica token fallita**: + ``` + La versione chiave del token non corrisponde + ``` + Soluzione: Verificare se la chiave è stata modificata, riottenere il token + +3. **Errore ambito autorizzazioni**: + ``` + L'ambito delle autorizzazioni del token non è valido + ``` + Soluzione: Utilizzare il token corretto, assicurarsi che Scope sia "api_gateway" + +4. **Token revocato**: + ``` + Il token è stato revocato globalmente + ``` + Soluzione: Riottenere il token, o verificare se è stata eseguita un'operazione di revoca globale + +## Vantaggi Architetturali + +### Vantaggi dopo la Rimozione di Redis + +1. **Semplificazione del deployment**: Non necessario server Redis +2. **Riduzione dei costi**: Ridotte le dipendenze infrastrutturali +3. **Maggiore affidabilità**: Ridotti i punti di guasto singolo +4. **Miglioramento delle prestazioni**: Nessuna chiamata di rete per verificare il token +5. **Semplificazione della manutenzione**: Ridotta la complessità di configurazione +6. **Supporto cloud-native**: Completamente stateless, adatto al deployment containerizzato + +--- + # JWT安全机制说明 ## 概述 @@ -158,7 +370,7 @@ curl http://localhost:8000/env \ ```bash # 1. 获取新令牌 curl -X POST http://localhost:8000/auth \ - -H "X-Gateway-API-Key: your-strong-secret-key" \ + -H "X-Gateway-API-Key: your-strong-secret-key-at-least-32-characters" \ -H "X-USER-ID: test-user" # 2. 使用令牌访问API diff --git a/backend/magic-gateway/docs/multi-environment-deployment.md b/backend/magic-gateway/docs/multi-environment-deployment.md index d148ec19d..e3db81314 100644 --- a/backend/magic-gateway/docs/multi-environment-deployment.md +++ b/backend/magic-gateway/docs/multi-environment-deployment.md @@ -1,3 +1,430 @@ +# Guida al Deployment Multi-Ambiente del Gateway API + +Questo documento spiega in dettaglio come utilizzare la tecnologia dei container Docker per implementare uno schema di deployment con tre ambienti indipendenti per il gateway API: test, pre-release (pre) e produzione (prod). + +## Panoramica della Soluzione + +Attraverso la tecnologia dei container Docker, possiamo creare istanze completamente isolate del gateway API per ogni ambiente, ciascuna con le proprie: +- File di configurazione +- Variabili d'ambiente +- Porte di rete +- Volumi di storage + +Questa soluzione offre i seguenti vantaggi: +- Isolamento ambientale: Garantisce che gli ambienti non si interferiscano reciprocamente +- Separazione della configurazione: Ogni ambiente utilizza file di configurazione indipendenti +- Consistenza del deployment: Garantisce che tutti gli ambienti utilizzino la stessa versione del codice +- Scalabilità: Facilita l'aggiunta di ulteriori ambienti (come sviluppo, QA, ecc.) +- Controllo delle risorse: Possibilità di allocare risorse diverse per ambienti diversi + +## Prerequisiti + +- Docker 20.10.x o versione superiore +- Docker Compose 2.x o versione superiore +- Git (per clonare il repository) +- Conoscenze di base delle operazioni da riga di comando + +## Passi di Implementazione + +### 1. Adeguamento della Struttura del Progetto + +Innanzitutto, adeguare la struttura del progetto per supportare la configurazione multi-ambiente: + +```bash +mkdir -p config/{test,pre,prod} +``` + +Creare la seguente struttura di directory: + +``` +magic-gateway/ +├── config/ # Directory di configurazione multi-ambiente +│ ├── test/ # Configurazione ambiente di test +│ │ └── .env # Variabili ambiente di test +│ ├── pre/ # Configurazione ambiente pre-release +│ │ └── .env # Variabili ambiente pre-release +│ └── prod/ # Configurazione ambiente produzione +│ └── .env # Variabili ambiente produzione +├── Dockerfile # File di costruzione del container +├── docker-compose.yml # Configurazione orchestrazione container +└── ... # Altri file del progetto +``` + +### 2. Creazione dei File di Configurazione Multi-Ambiente + +Creare file di configurazione delle variabili d'ambiente indipendenti per ogni ambiente. + +#### File di Configurazione Ambiente Test (config/test/.env) + +```ini +# Configurazione ambiente test +JWT_SECRET=test-jwt-secret-key-change-me +API_GATEWAY_VERSION=1.0.0-test +MAGIC_GATEWAY_DEBUG=true +PORT=8001 +MAGIC_GATEWAY_API_KEY=test-gateway-api-key + +# Configurazione servizio OpenAI ambiente test +OPENAI_API_KEY=sk-test-xxxx +OPENAI_API_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-3.5-turbo + +# Configurazione altri servizi ambiente test +MAGIC_API_KEY=test-xxx +MAGIC_API_BASE_URL=https://api.magic-test.com/v1 +MAGIC_MODEL=gpt-4-test +``` + +#### File di Configurazione Ambiente Pre-Release (config/pre/.env) + +```ini +# Configurazione ambiente pre-release +JWT_SECRET=pre-jwt-secret-key-change-me +API_GATEWAY_VERSION=1.0.0-pre +MAGIC_GATEWAY_DEBUG=true +PORT=8002 +MAGIC_GATEWAY_API_KEY=pre-gateway-api-key + +# Configurazione servizio OpenAI ambiente pre-release +OPENAI_API_KEY=sk-pre-xxxx +OPENAI_API_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-4 + +# Configurazione altri servizi ambiente pre-release +MAGIC_API_KEY=pre-xxx +MAGIC_API_BASE_URL=https://api.magic-pre.com/v1 +MAGIC_MODEL=gpt-4-pre +``` + +#### File di Configurazione Ambiente Produzione (config/prod/.env) + +```ini +# Configurazione ambiente produzione +JWT_SECRET=prod-jwt-secret-key-change-me +API_GATEWAY_VERSION=1.0.0 +MAGIC_GATEWAY_DEBUG=false +PORT=8003 +MAGIC_GATEWAY_API_KEY=prod-gateway-api-key + +# Configurazione servizio OpenAI ambiente produzione +OPENAI_API_KEY=sk-prod-xxxx +OPENAI_API_BASE_URL=https://api.openai.com/v1 +OPENAI_MODEL=gpt-4 + +# Configurazione altri servizi ambiente produzione +MAGIC_API_KEY=prod-xxx +MAGIC_API_BASE_URL=https://api.magic.com/v1 +MAGIC_MODEL=gpt-4o-global +``` + +### 3. Aggiornamento del Dockerfile + +Ottimizzare il Dockerfile per supportare il deployment multi-ambiente: + +```dockerfile +FROM golang:1.20-alpine AS builder +WORKDIR /app +COPY go.mod go.sum ./ +RUN go mod download +COPY . . +RUN CGO_ENABLED=0 GOOS=linux go build -o api-gateway main.go + +FROM alpine:latest +WORKDIR /app +COPY --from=builder /app/api-gateway . +# Creare directory di configurazione +RUN mkdir -p /app/config +# Impostare variabili d'ambiente +ENV PORT=8000 +ENV MAGIC_GATEWAY_ENV=dev +# Esporre porta +EXPOSE 8000 +# Comando di avvio +CMD ["./api-gateway"] +``` + +### 4. Creazione della Configurazione Docker Compose Multi-Ambiente + +Creare un file `docker-compose.yml` che supporti ambienti multipli: + +```yaml +version: '3' + +services: + magic-gateway: + build: + context: . + dockerfile: Dockerfile + restart: always + environment: + - PORT=${PORT:-8000} + - MAGIC_GATEWAY_ENV=${ENV:-dev} + - JWT_SECRET=${JWT_SECRET:-default-secret-key} + - MAGIC_GATEWAY_API_KEY=${API_KEY:-default-api-key} + - MAGIC_GATEWAY_DEBUG=${DEBUG:-false} + ports: + - "${EXTERNAL_PORT:-8000}:${PORT:-8000}" + volumes: + - ./config/${ENV:-dev}/.env:/app/.env + networks: + - gateway-network + +networks: + gateway-network: + driver: bridge +``` + +### 5. Creazione di Script di Avvio Rapido + +Creare uno script `deploy.sh` per semplificare il processo di deployment multi-ambiente: + +```bash +#!/bin/bash + +# Definire colori +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' # Ripristinare colore predefinito + +# Informazioni di aiuto +function show_help { + echo -e "${YELLOW}Script di Deployment Multi-Ambiente Gateway API${NC}" + echo "Utilizzo: $0 [ambiente] [operazione]" + echo "" + echo "Opzioni ambiente:" + echo " test - Ambiente test (porta 8001)" + echo " pre - Ambiente pre-release (porta 8002)" + echo " prod - Ambiente produzione (porta 8003)" + echo "" + echo "Opzioni operazione:" + echo " start - Avviare ambiente specificato" + echo " stop - Fermare ambiente specificato" + echo " restart - Riavviare ambiente specificato" + echo " logs - Visualizzare log ambiente specificato" + echo " status - Visualizzare stato ambiente specificato" + echo " all - Operare su tutti gli ambienti" + echo "" + echo "Esempi:" + echo " $0 test start - Avviare ambiente test" + echo " $0 all start - Avviare tutti gli ambienti" + echo " $0 prod logs - Visualizzare log ambiente produzione" +} + +# Verifica parametri ambiente +if [ "$1" != "test" ] && [ "$1" != "pre" ] && [ "$1" != "prod" ] && [ "$1" != "all" ]; then + show_help + exit 1 +fi + +# Verifica parametri operazione +if [ "$2" != "start" ] && [ "$2" != "stop" ] && [ "$2" != "restart" ] && [ "$2" != "logs" ] && [ "$2" != "status" ]; then + show_help + exit 1 +fi + +# Avviare ambiente specificato +function start_env { + local env=$1 + local port + local api_key + local jwt_secret + local debug + + echo -e "${GREEN}Avvio ambiente $env in corso...${NC}" + + case $env in + test) + port=8001 + api_key="test-gateway-api-key" + jwt_secret="test-jwt-secret-key" + debug="true" + ;; + pre) + port=8002 + api_key="pre-gateway-api-key" + jwt_secret="pre-jwt-secret-key" + debug="true" + ;; + prod) + port=8003 + api_key="prod-gateway-api-key" + jwt_secret="prod-jwt-secret-key" + debug="false" + ;; + esac + + ENV=$env PORT=$port EXTERNAL_PORT=$port API_KEY=$api_key JWT_SECRET=$jwt_secret DEBUG=$debug \ + docker-compose -p magic-gateway-$env up -d + + echo -e "${GREEN}Ambiente $env avviato, indirizzo di accesso: http://localhost:$port${NC}" +} + +# Fermare ambiente specificato +function stop_env { + local env=$1 + echo -e "${YELLOW}Fermando ambiente $env...${NC}" + docker-compose -p magic-gateway-$env down + echo -e "${YELLOW}Ambiente $env fermato${NC}" +} + +# Visualizzare log ambiente specificato +function view_logs { + local env=$1 + echo -e "${GREEN}Visualizzando log ambiente $env...${NC}" + docker-compose -p magic-gateway-$env logs -f +} + +# Verificare stato ambiente specificato +function check_status { + local env=$1 + echo -e "${GREEN}Stato ambiente $env:${NC}" + docker-compose -p magic-gateway-$env ps +} + +# Elaborare operazione +function process_operation { + local env=$1 + local operation=$2 + + case $operation in + start) + start_env $env + ;; + stop) + stop_env $env + ;; + restart) + stop_env $env + start_env $env + ;; + logs) + view_logs $env + ;; + status) + check_status $env + ;; + esac +} + +# Elaborare tutti gli ambienti +function process_all_envs { + local operation=$1 + + for env in test pre prod; do + process_operation $env $operation + done +} + +# Flusso principale +if [ "$1" == "all" ]; then + process_all_envs $2 +else + process_operation $1 $2 +fi +``` + +Assicurarsi che lo script abbia i permessi di esecuzione: + +```bash +chmod +x deploy.sh +``` + +### 6. Deployment e Gestione + +Ora è possibile utilizzare lo script `deploy.sh` per gestire facilmente i diversi ambienti: + +```bash +# Avviare ambiente test +./deploy.sh test start + +# Avviare ambiente pre-release +./deploy.sh pre start + +# Avviare ambiente produzione +./deploy.sh prod start + +# Avviare tutti gli ambienti +./deploy.sh all start + +# Visualizzare log ambiente test +./deploy.sh test logs + +# Fermare ambiente produzione +./deploy.sh prod stop +``` + +## Modalità di Accesso agli Ambienti + +I gateway API dei diversi ambienti sono accessibili attraverso porte diverse: + +- Ambiente test: http://localhost:8001 +- Ambiente pre-release: http://localhost:8002 +- Ambiente produzione: http://localhost:8003 + +## Isolamento Ambientale e Indipendenza dei Dati + +- Ogni ambiente utilizza container Docker indipendenti, garantendo l'isolamento dei processi +- Ogni ambiente utilizza file di variabili d'ambiente indipendenti, garantendo l'isolamento della configurazione +- Ogni ambiente utilizza porte indipendenti, garantendo l'isolamento di rete +- Le chiavi JWT sono impostate indipendentemente in ogni ambiente, garantendo che i token non siano intercambiabili + +## Differenze nelle Caratteristiche degli Ambienti + +1. **Ambiente test**: + - Modalità debug abilitata, output di log dettagliati + - Utilizzo di chiavi API di test + - Possibilità di utilizzare modelli con configurazione inferiore per i test + +2. **Ambiente pre-release**: + - Modalità debug abilitata, facilita la risoluzione dei problemi + - Utilizzo di configurazione vicina alla produzione + - Utilizzato per verifica funzionale e test delle prestazioni + +3. **Ambiente produzione**: + - Modalità debug disabilitata, migliora le prestazioni + - Utilizzo di chiavi API ufficiali + - Utilizzo della configurazione di modello più stabile + +## Raccomandazioni di Sicurezza + +1. I file di configurazione dell'ambiente produzione dovrebbero essere custoditi adeguatamente, evitando la divulgazione di informazioni sensibili +2. Le chiavi JWT e API di ogni ambiente dovrebbero essere diverse +3. Ruotare periodicamente le chiavi di ogni ambiente +4. L'ambiente produzione dovrebbe utilizzare HTTPS o protezione di rete interna +5. Utilizzare l'iniezione di variabili d'ambiente per informazioni sensibili, evitando di codificare informazioni sensibili nei file di configurazione + +## Risoluzione dei Problemi + +1. Visualizzare i log del container + ```bash + ./deploy.sh logs + ``` + +2. Verificare i file di configurazione dell'ambiente + ```bash + cat config//.env + ``` + +3. Verificare lo stato del container + ```bash + ./deploy.sh status + ``` + +4. Riavviare il servizio + ```bash + ./deploy.sh restart + ``` + +## Estensioni e Ottimizzazioni + +1. **Aggiungere monitoraggio**: Integrare Prometheus e Grafana per monitorare lo stato dei container +2. **Load balancing**: In scenari ad alto traffico, è possibile scalare orizzontalmente il servizio attraverso Docker Compose +3. **Integrazione CI/CD**: Integrare il deployment multi-ambiente nel flusso CI/CD +4. **Test automatizzati**: Aggiungere script di test automatizzati per ogni ambiente + +--- + # API网关的多环境部署指南 本文档详细说明如何使用Docker容器技术为API网关实现测试(test)、预发布(pre)和生产(production)三套独立环境的部署方案。 @@ -425,4 +852,4 @@ chmod +x deploy.sh --- -本部署方案通过Docker容器技术实现了API网关的多环境部署，确保各环境之间的隔离性和配置独立性，同时保持代码的一致性，便于管理和维护。 \ No newline at end of file +本部署方案通过Docker容器技术实现了API网关的多环境部署，确保各环境之间的隔离性和配置独立性，同时保持代码的一致性，便于管理和维护。 diff --git a/backend/magic-service/README.md b/backend/magic-service/README.md index a6959685b..4dd805595 100644 --- a/backend/magic-service/README.md +++ b/backend/magic-service/README.md @@ -1,3 +1,138 @@ +# Magic Service ⚡ + +## 📋 Panoramica del Progetto + +Magic Service è un'applicazione microservizi PHP ad alte prestazioni basata sul framework Hyperf, che utilizza il driver di coroutine Swow per implementare capacità di elaborazione ad alta concorrenza. Questo progetto integra molteplici moduli funzionali, inclusi ricerca AI, funzionalità di chat, elaborazione file, gestione autorizzazioni, ecc., con l'obiettivo di fornire una soluzione di servizio completa. + +## ✨ Caratteristiche Principali + +- **🔍 Funzionalità di Ricerca AI**: Integrazione delle API di motori di ricerca come Google, fornisce capacità di ricerca intelligente +- **💬 Sistema di Chat**: Supporta comunicazioni in tempo reale e gestione delle conversazioni +- **📁 Elaborazione File**: Funzionalità di caricamento, download e gestione file +- **🔄 Gestione Processi**: Supporta configurazione ed esecuzione dei flussi di lavoro +- **🤖 Funzionalità Assistente**: Supporto per funzionalità assistente estensibili + +## 🛠️ Requisiti di Sistema + +- PHP >= 8.3 +- Estensione Swow +- Estensione Redis +- Estensione PDO +- Altre estensioni: bcmath, curl, fileinfo, openssl, xlswriter, zlib, ecc. +- Composer + +## 📦 Installazione e Distribuzione + +### 1. 🧬 Clonazione del Progetto + +```bash +git clone https://github.com/dtyq/magic.git +cd magic-service +``` + +### 2. 📥 Installazione Dipendenze + +```bash +composer install +``` + +### 3. ⚙️ Configurazione Ambiente + +Copia il file di configurazione dell'ambiente e modificalo secondo necessità: + +```bash +cp .env.example .env +``` + +### 🗄️ Migrazione Database + +```bash +php bin/hyperf.php migrate +``` + +## 🚀 Esecuzione dell'Applicazione + +### Avvio del Servizio Frontend + +```bash +cd static/web && npm install && npm run dev +``` + +### Avvio del Servizio Backend + +```bash +php bin/hyperf.php start +``` + +È anche possibile utilizzare lo script di avvio: + +```bash +sh start.sh +``` + +## 🛠️ Guida allo Sviluppo + +### Struttura del Progetto + +- `app/` - Codice dell'applicazione + - `Application/` - Codice del livello applicazione + - `Domain/` - Codice del livello dominio + - `Infrastructure/` - Codice del livello infrastruttura + - `Interfaces/` - Codice del livello interfaccia + - `ErrorCode/` - Definizioni codici errore + - `Listener/` - Listener eventi +- `config/` - File di configurazione +- `migrations/` - File migrazione database +- `test/` - Test unitari +- `bin/` - Script eseguibili +- `static/` - File risorse statiche + +### Standard di Codice + +Il progetto utilizza PHP-CS-Fixer per il controllo e la correzione dello stile del codice: + +```bash +composer fix +``` + +Utilizza PHPStan per l'analisi statica del codice: + +```bash +composer analyse +``` + +### Test Unitari + +Utilizza il seguente comando per eseguire i test unitari: + +```bash +vendor/bin/phpunit +# oppure +composer test +``` + +## 🐳 Distribuzione Docker + +Il progetto fornisce un Dockerfile, è possibile utilizzare il seguente comando per costruire l'immagine: + +```bash +docker build -t magic-service . +``` + +## 🤝 Guida ai Contributi + +1. Fork del progetto +2. Crea un branch per la funzionalità (`git checkout -b feature/amazing-feature`) +3. Commit delle modifiche (`git commit -m 'Add some amazing feature'`) +4. Push al branch (`git push origin feature/amazing-feature`) +5. Invia una Pull Request + +## 📄 Licenza + +Questo progetto adotta la licenza MIT - per i dettagli consulta il file LICENSE + +--- + # Magic Service ## 项目概述 @@ -36,9 +171,6 @@ cd magic-service composer install ``` - - - ### 3. 环境配置 复制环境配置文件并根据需要修改： diff --git a/backend/magic-service/app/Interfaces/Asr/CHANGELOG.md b/backend/magic-service/app/Interfaces/Asr/CHANGELOG.md index 7e3c44800..f557bdb80 100644 --- a/backend/magic-service/app/Interfaces/Asr/CHANGELOG.md +++ b/backend/magic-service/app/Interfaces/Asr/CHANGELOG.md @@ -1,3 +1,75 @@ +# Registro delle Modifiche API Token ASR + +## 2024-01-XX - Aggiunto parametro refresh e modifica duration + +### Nuove Funzionalità +- ✅ Aggiunto parametro `refresh` all'interfaccia `GET /api/v1/asr/tokens` +- ✅ Supporto per il refresh forzato del token, quando `refresh=true` cancella la cache e riottiene il token + +### Contenuto delle Modifiche +- 🔄 Duration predefinito cambiato da 3600 secondi a 7200 secondi (2 ore) +- 🔄 Non accetta più il parametro duration esterno, fisso a 7200 secondi +- 🔄 Ottimizzata la logica di cache, supporto per refresh su richiesta +- 🔄 Campo `duration` visualizzato dinamicamente: nuovi token mostrano 7200 secondi, token in cache mostrano il tempo rimanente + +### Modifiche all'Interfaccia +- **GET /api/v1/asr/tokens** + - Nuovo: parametro `refresh` (boolean, predefinito false) + - Rimosso: parametro `duration` + - Modificato: Validità token fissata a 7200 secondi + - Ottimizzato: campo `duration` mostra dinamicamente il tempo rimanente di validità + +### Miglioramenti Tecnici +- 🚀 Migliorata l'esperienza d'uso del token, ridotto il problema delle scadenze frequenti +- 🔧 Aumentata la flessibilità del controllo della cache +- 📊 Visualizzazione dinamica del tempo rimanente del token, migliorata l'esperienza utente +- 📝 Aggiornata la documentazione API completa e gli esempi d'uso + +## 2024-01-XX - Refactoring Completato + +### Funzionalità Rimosse +- ❌ Rimosso l'interfaccia `GET /api/v1/asr/config` +- ❌ Eliminata la classe `AsrTokenController` +- ❌ Eliminato il comando di test `TestJwtTokenCommand` + +### Nuove Funzionalità +- ✅ Creata la classe `AsrTokenApi`, conforme al pattern Facade del progetto +- ✅ Creata la classe base `AbstractApi`, fornisce funzionalità generiche +- ✅ Refactored la struttura delle directory, utilizza sottodirectory `Facade` + +### Funzionalità Mantenute +- ✅ `GET /api/v1/asr/tokens` - Ottieni JWT Token +- ✅ `DELETE /api/v1/asr/tokens` - Cancella cache JWT Token +- ✅ Meccanismo di autenticazione utente +- ✅ Meccanismo di cache Redis +- ✅ Ottimizzazione prestazioni (miglioramento del 93.8%) + +### Miglioramenti Tecnici +- 📁 Struttura delle directory più conforme agli standard del progetto +- 🏗️ Utilizzo del pattern Facade, eredita da AbstractApi +- 🧹 Codice più pulito, rimossi gli interfaccia di configurazione non necessari +- 📝 Mantenuta documentazione completa e gestione degli errori + +## Struttura dei File + +``` +app/Interfaces/Asr/ +├── Facade/ +│ ├── AbstractApi.php # Classe API base +│ └── AsrTokenApi.php # API JWT Token +├── README.md # Documentazione API +└── CHANGELOG.md # Registro delle modifiche +``` + +## Mappatura delle Route + +``` +GET /api/v1/asr/tokens → AsrTokenApi::show() +DELETE /api/v1/asr/tokens → AsrTokenApi::destroy() +``` + +--- + # ASR Token API 变更日志 ## 2024-01-XX - 新增refresh参数和duration修改 @@ -66,4 +138,4 @@ app/Interfaces/Asr/ ``` GET /api/v1/asr/tokens → AsrTokenApi::show() DELETE /api/v1/asr/tokens → AsrTokenApi::destroy() -``` \ No newline at end of file +``` diff --git a/backend/magic-service/storage/prompt/tool_call.md b/backend/magic-service/storage/prompt/tool_call.md index 5b0f09e0b..daaf21bb1 100644 --- a/backend/magic-service/storage/prompt/tool_call.md +++ b/backend/magic-service/storage/prompt/tool_call.md @@ -1,3 +1,43 @@ +# Esperto di Estrazione Parametri Strumenti + +Sei un esperto di estrazione parametri strumenti, specializzato nell'estrarre i parametri necessari per le chiamate agli strumenti dal contenuto delle chat degli utenti, e nell'output forzato dei risultati in formato JSON. Quando non è possibile estrarre i parametri, fornire valori predefiniti in base al tipo (vedi regole dettagliate), assicurando che lo strumento possa essere chiamato normalmente. Di seguito sono riportate le istruzioni del compito e le norme operative. + +## I. Specifiche di Chiamata Strumenti +```json +:tool +``` + +## II. Passi Operativi +1. Analizza il contenuto della chat: Leggi i record delle chat o le istruzioni fornite dall'utente, comprendi le esigenze e le intenzioni dell'utente. +2. Estrai i parametri necessari: In base al contenuto della chat, estrai i parametri code e file_url necessari per la chiamata allo strumento. +3. Assicurati la conformità alle specifiche: Assicurati che i parametri estratti seguano rigorosamente le regole menzionate nelle specifiche. +4. Genera output JSON: Secondo le specifiche di chiamata degli strumenti, outputta il contenuto dei parametri estratti in formato JSON. + +## III. Regole Formato JSON Generato +1. Vietato andare a capo: Il contenuto JSON deve essere restituito in forma singola, rimuovendo tutti i caratteri di nuova riga, assicurando che il formato di output sia conciso e chiaro. +2. Vietato l'involucro del blocco di codice: Nell'output del formato JSON, restituire direttamente il contenuto della stringa JSON pura, non è permesso utilizzare blocchi di codice (come ```json). +3. Restituire rigorosamente secondo il formato JSON delle specifiche di chiamata degli strumenti, è necessario restituire solo il formato JSON della parte dei parametri. + +## IV. Esempi + +### 4.1 Scenario 1: Estrazione Completa dei Parametri + +**Input (contenuto chat)**: Si prega di estrarre il nome di ogni tabella, i nomi delle colonne e le prime 10 righe di dati dal file Excel, il link del file è https://example.com/sample.xlsx. + +**Output (parametri JSON estratti)**: Secondo le specifiche dei parametri degli strumenti, estrarre i parametri, i parametri che non possono essere proposti utilizzano valori predefiniti. + +### 4.2 Scenario 2: Impossibile Estrarre Completamente i Parametri, Fornire Valori Predefiniti in Base al Tipo + +**Input (contenuto chat)**: Ho bisogno di estrarre la struttura dei dati Excel, ma non c'è una descrizione specifica del file. Oppure domanda: Chi sei. ecc. non correlato all'argomento. + +**Output (parametri JSON con valori predefiniti)**: Secondo le specifiche dei parametri degli strumenti, fornire valori predefiniti del tipo, come il valore predefinito di string è "", il valore predefinito di number è 0, il valore predefinito di array è [], il valore predefinito di object è {}. + +## V. Obiettivi +1. Indipendentemente da quanto complesso sia il contenuto della chat in input, devi assicurarti che i parametri JSON generati siano completi e conformi alle specifiche, aiutando lo strumento a completare accuratamente le esigenze dell'utente. +2. In ogni caso, restituire solo contenuto in formato JSON. + +--- + # 工具参数提取专家 你是一名工具参数提取专家，专门根据用户聊天内容，提取工具调用所需的参数，并强制以 JSON 格式输出结果。当无法提取参数时，根据类型给出默认值（详见规则），确保工具能够正常调用。以下是你的任务说明和操作规范。 @@ -34,4 +74,4 @@ ## 五. 目标 1. 无论输入的聊天内容如何复杂，你都需要确保生成的 JSON 参数完整且符合规范，帮助工具准确完成用户需求。 -2. 无论如何只能返回 JSON 格式内容。 \ No newline at end of file +2. 无论如何只能返回 JSON 格式内容。 diff --git a/backend/rule-engine-core/README.md b/backend/rule-engine-core/README.md index 09be50e3c..f0b38e537 100644 --- a/backend/rule-engine-core/README.md +++ b/backend/rule-engine-core/README.md @@ -1,3 +1,210 @@ +# Motore di Regole Core ⚙️ + +## ✅ Funzionalità Implementate + +1. Traduzione delle specifiche JSR-94 +2. Servizio di regole di tipo script PHP + +## 📝 Esempi + +### Registrazione del Servizio di Regole + +```php +use Dtyq\RuleEngineCore\PhpScript\RuleServiceProvider; +use Dtyq\RuleEngineCore\Standards\RuleServiceProviderManager; + +$uri = RuleServiceProvider::RULE_SERVICE_PROVIDER; +$container = ApplicationContext::getContainer(); +RuleServiceProviderManager::registerRuleServiceProvider($uri, RuleServiceProvider::class, $container); +``` + +Il repository delle regole script PHP predefinito è efficace a livello di processo (repository funzioni) e coroutine (gruppo regole). Se è necessario un repository personalizzato (ad esempio utilizzando cache o DB per l'archiviazione), è possibile utilizzare il seguente metodo per la sostituzione. + +```php +use Dtyq\RuleEngineCore\PhpScript\RuleServiceProvider; +use Dtyq\RuleEngineCore\Standards\RuleServiceProviderManager; + +$provider = new RuleServiceProvider(); +$provider + ->setExecutionSetRepository(new CustomExecutionSetRepository()) //Utilizzo repository gruppo regole personalizzato + ->setFunctionRepository(new CustomFunctionRepository()); //Utilizzo repository funzioni personalizzato +$container = ApplicationContext::getContainer(); +RuleServiceProviderManager::registerRuleServiceProvider(RuleServiceProvider::RULE_SERVICE_PROVIDER, $provider, $container); +``` + +I repository di funzioni e gruppi di regole devono implementare `\Dtyq\RuleEngineCore\PhpScript\Repository\ExpressionFunctionRepositoryInterface` e `\Dtyq\RuleEngineCore\PhpScript\Repository\RuleExecutionSetRepositoryInterface`. + +Inoltre, si consiglia di registrare il servizio di regole all'avvio del framework. L'esempio seguente completa la registrazione del servizio di regole ascoltando gli eventi del framework. + +```php +use Hyperf\Event\Contract\ListenerInterface; +use Hyperf\Utils\ApplicationContext; +use Dtyq\RuleEngineCore\PhpScript\RuleServiceProvider; +use Dtyq\RuleEngineCore\Standards\RuleServiceProviderManager; +use Hyperf\Event\Annotation\Listener; + +#[Listener] +class AutoRegister implements ListenerInterface +{ + public function listen(): array + { + return [ + \Hyperf\Framework\Event\BootApplication::class, + ]; + } + + public function process(object $event): void + { + $uri = RuleServiceProvider::RULE_SERVICE_PROVIDER; + $container = ApplicationContext::getContainer(); + RuleServiceProviderManager::registerRuleServiceProvider($uri, RuleServiceProvider::class, $container); + } +} +``` + +### Registrazione delle Funzioni + +Gli script e le espressioni per default proibiscono l'esecuzione di qualsiasi funzione, gli utenti possono registrarle tramite il seguente metodo. + +```php +$uri = RuleServiceProvider::RULE_SERVICE_PROVIDER; +$ruleProvider = RuleServiceProviderManager::getRuleServiceProvider($uri); +$admin = $ruleProvider->getRuleAdministrator(); +$executableCode = new ExecutableFunction('add', function ($arg1, $arg2) { + return $arg1 + $arg2; +}); +$admin->registerExecutableCode($executableCode); +``` + +Metodo di registrazione rapida basato sulle funzioni native PHP: + +```php +$uri = RuleServiceProvider::RULE_SERVICE_PROVIDER; +$ruleProvider = RuleServiceProviderManager::getRuleServiceProvider($uri); +$admin = $ruleProvider->getRuleAdministrator(); +$executableCode = ExecutableFunction::fromPhp('is_array', 'is_array2'); //Nello script è necessario utilizzare is_array2 per la chiamata +$admin->registerExecutableCode($executableCode); +``` + +Da notare, si prega di non scrivere codice che potrebbe causare il cambio di coroutine all'interno delle funzioni. + +### Registrazione del Gruppo di Esecuzione Regole + +```php +use Dtyq\RuleEngineCore\PhpScript\RuleServiceProvider; +use Dtyq\RuleEngineCore\Standards\RuleServiceProviderManager; +use Dtyq\RuleEngineCore\Standards\Admin\InputType; +use Dtyq\RuleEngineCore\PhpScript\RuleType; + +$uri = RuleServiceProvider::RULE_SERVICE_PROVIDER; +$ruleProvider = RuleServiceProviderManager::getRuleServiceProvider($uri); +$admin = $ruleProvider->getRuleAdministrator(); +$ruleExecutionSetProvider = $admin->getRuleExecutionSetProvider(InputType::from(InputType::String)); +$input = ['$a + $b']; //Contenuto script o espressione +$properties = new RuleExecutionSetProperties(); +$properties->setName('add-rule'); +$properties->setRuleType(RuleType::Expression); // Tipo di regola, supporta script o tipo espressione. Se non definito, è script per default. +$set = $ruleExecutionSetProvider->createRuleExecutionSet($input, $properties); +$admin->registerRuleExecutionSet('mysample', $set, $properties); +``` + +### Esecuzione del Gruppo di Regole + +```php +use Dtyq\RuleEngineCore\Standards\RuleSessionType; + +$runtime = $ruleProvider->getRuleRuntime(); +$properties = new RuleExecutionSetProperties(); +$ruleSession = $runtime->createRuleSession('mysample', $properties, RuleSessionType::from(RuleSessionType::Stateless)); +$inputs = []; +$inputs['a'] = 1; +$inputs['b'] = 2; +$res = $ruleSession->executeRules($inputs); +$ruleSession->release(); +``` + +### Albero Sintassi Astratta (AST) + +Quando non esistono segnaposto nella regola, l'analisi sintattica verrà eseguita durante la creazione del gruppo di regole, a quel punto sarà possibile ottenere l'albero sintassi astratta (AST). + +```php +use Dtyq\RuleEngineCore\PhpScript\RuleServiceProvider; +use Dtyq\RuleEngineCore\Standards\RuleServiceProviderManager; +use Dtyq\RuleEngineCore\Standards\Admin\InputType; +use Dtyq\RuleEngineCore\PhpScript\RuleType; +use PhpParser\Node; +use PhpParser\NodeTraverser; +use PhpParser\NodeVisitorAbstract; + +$uri = RuleServiceProvider::RULE_SERVICE_PROVIDER; +$ruleProvider = RuleServiceProviderManager::getRuleServiceProvider($uri); +$admin = $ruleProvider->getRuleAdministrator(); +$ruleExecutionSetProvider = $admin->getRuleExecutionSetProvider(InputType::from(InputType::String)); +$input = ['$a + $b']; //Non contiene segnaposto +$properties = new RuleExecutionSetProperties(); +$properties->setName('add-rule'); +$properties->setRuleType(RuleType::Expression); // Tipo di regola, supporta script o tipo espressione. Se non definito, è script per default. +$set = $ruleExecutionSetProvider->createRuleExecutionSet($input, $properties); +//Eseguire azioni di validazione di analisi personalizzate +$ast = $set->getAsts(); +$traverser = new NodeTraverser(); +$visitor = new class() extends NodeVisitorAbstract { + public function leaveNode(Node $node) + { + var_dump($node); + } +}; +$traverser->addVisitor($visitor); +foreach ($ast as $stmts) { + $traverser->traverse($stmts); +} +``` + +Se la regola contiene segnaposto, è necessario attendere la fase di esecuzione delle regole per ottenere l'albero sintassi astratta (AST). + +```php +use Dtyq\RuleEngineCore\PhpScript\RuleServiceProvider; +use Dtyq\RuleEngineCore\Standards\RuleServiceProviderManager; +use Dtyq\RuleEngineCore\Standards\Admin\InputType; +use Dtyq\RuleEngineCore\PhpScript\RuleType; +use PhpParser\Node; +use PhpParser\NodeTraverser; +use PhpParser\NodeVisitorAbstract; + +$uri = RuleServiceProvider::RULE_SERVICE_PROVIDER; +$ruleProvider = RuleServiceProviderManager::getRuleServiceProvider($uri); +$admin = $ruleProvider->getRuleAdministrator(); +$ruleExecutionSetProvider = $admin->getRuleExecutionSetProvider(InputType::from(InputType::String)); +$input = ['if( {{ruleEnableCondition}} ) return $so;']; //Contiene segnaposto +$properties = new RuleExecutionSetProperties(); +$properties->setName('testPlaceholder-rule'); +$properties->setRuleType(RuleType::Script); // Tipo di regola, supporta script o tipo espressione. Se non definito, è script per default. +$properties->setResolvePlaceholders(true); +$set = $ruleExecutionSetProvider->createRuleExecutionSet($input, $properties); +$admin->registerRuleExecutionSet('mysample', $set, $properties); +//Dopo la registrazione, passare le informazioni segnaposto e i fatti per preparare l'esecuzione delle regole +$runtime = $ruleProvider->getRuleRuntime(); +$properties = new RuleExecutionSetProperties(); +$properties->setPlaceholders(['ruleEnableCondition' => '1 == 1']); +$ruleSession = $runtime->createRuleSession('mysample', $properties, RuleSessionType::from(RuleSessionType::Stateless)); +$inputs = []; +$inputs['so'] = 'aaaa111122'; +$res = $ruleSession->getAsts(); +$traverser = new NodeTraverser(); +$visitor = new class() extends NodeVisitorAbstract { + public function leaveNode(Node $node) + { + var_dump($node); + } +}; +$traverser->addVisitor($visitor); +foreach ($res as $stmts) { + $traverser->traverse($stmts); +} +``` + +--- + # rule engine core ## 已实现功能 diff --git a/backend/sandbox-gateway/README.md b/backend/sandbox-gateway/README.md index cccf80445..4405412be 100644 --- a/backend/sandbox-gateway/README.md +++ b/backend/sandbox-gateway/README.md @@ -1,3 +1,193 @@ +# Sandbox Gateway Service 🏗️ + +Il Sandbox Gateway Service fornisce interfacce HTTP e WebSocket, permettendo ai client di creare e gestire container Docker sandbox, e comunicare con i container attraverso connessioni WebSocket. + +## ✨ Caratteristiche Principali + +- Creazione di container Docker sandbox isolati +- Separazione del processo di creazione e connessione sandbox +- Fornitura di API RESTful per gestire il ciclo di vita dei sandbox +- Esecuzione di comandi all'interno dei container tramite interfaccia WebSocket +- Pulizia automatica dei container inattivi + +## 📋 Prerequisiti + +- Docker installato +- Python 3.8+ +- Immagine container sandbox `sandbox-websocket-image` già costruita + +## 🚀 Avvio Rapido + +Usa lo script di avvio fornito per avviare il servizio: + +```bash +./start.sh +``` + +Per default, il servizio si avvierà sulla porta 8003. Se hai bisogno di specificare una porta diversa, puoi passarla come parametro: + +```bash +./start.sh 8080 +``` + +## 📚 Riferimento API + +### HTTP API + +| Endpoint | Metodo | Descrizione | +|----------|--------|-------------| +| `/sandboxes` | POST | Crea un nuovo container sandbox | +| `/sandboxes` | GET | Ottieni la lista di tutti i container sandbox | +| `/sandboxes/{sandbox_id}` | GET | Ottieni informazioni sul sandbox specificato | +| `/sandboxes/{sandbox_id}` | DELETE | Elimina il container sandbox specificato | + +#### Creazione Sandbox + +**Richiesta:** +``` +POST /sandboxes +``` + +**Risposta:** +```json +{ + "sandbox_id": "abcd1234", + "status": "created", + "message": "Container sandbox creato con successo" +} +``` + +#### Ottieni Lista Sandbox + +**Richiesta:** +``` +GET /sandboxes +``` + +**Risposta:** +```json +[ + { + "sandbox_id": "abcd1234", + "status": "idle", + "created_at": 1648371234.567, + "ip_address": "172.17.0.2" + }, + { + "sandbox_id": "efgh5678", + "status": "connected", + "created_at": 1648371345.678, + "ip_address": "172.17.0.3" + } +] +``` + +#### Ottieni Informazioni Sandbox + +**Richiesta:** +``` +GET /sandboxes/{sandbox_id} +``` + +**Risposta:** +```json +{ + "sandbox_id": "abcd1234", + "status": "idle", + "created_at": 1648371234.567, + "ip_address": "172.17.0.2" +} +``` + +#### Elimina Sandbox + +**Richiesta:** +``` +DELETE /sandboxes/{sandbox_id} +``` + +**Risposta:** +```json +{ + "message": "Sandbox abcd1234 eliminato con successo" +} +``` + +### WebSocket API + +| Endpoint | Descrizione | +|----------|-------------| +| `/ws/{sandbox_id}` | Connetti al sandbox specificato via WebSocket | + +#### Connessione al Sandbox + +Formato URL connessione WebSocket: +``` +ws://localhost:8003/ws/{sandbox_id} +``` + +Dopo la connessione a questo endpoint, il servizio: +1. Si connette al container sandbox specificato +2. Stabilisce comunicazione bidirezionale tra client e container +3. Alla disconnessione non distrugge automaticamente il container, che diventa inattivo + +## 📨 Formato Messaggi + +### Invio Comandi + +```json +{ + "command": "ls -la", + "request_id": "optional-unique-id" +} +``` + +Se non fornisci `request_id`, il servizio ne genererà uno automaticamente. + +### Ricezione Risposte + +```json +{ + "request_id": "same-as-request", + "command": "ls -la", + "success": true, + "output": "command output", + "error": "error message if any", + "returncode": 0, + "timestamp": "2023-03-27T12:34:56.789" +} +``` + +## 🔄 Flusso di Utilizzo + +1. Crea un sandbox tramite interfaccia HTTP: + ``` + POST /sandboxes + ``` + +2. Ottieni l'ID sandbox dalla risposta + +3. Usa l'ID sandbox per stabilire connessione WebSocket: + ``` + ws://localhost:8003/ws/{sandbox_id} + ``` + +4. Invia comandi e ricevi risultati tramite WebSocket + +5. Una volta finito, puoi eliminare il sandbox: + ``` + DELETE /sandboxes/{sandbox_id} + ``` + +## ⚠️ Note di Sicurezza + +- I container vengono eseguiti nella rete bridge Docker predefinita +- Il servizio è destinato solo per ambienti di sviluppo e test, non raccomandato per uso diretto in produzione +- I container verranno automaticamente puliti dopo un'ora di inattività +- Gli ID sandbox dovrebbero essere custoditi con cura, chiunque conosca l'ID sandbox può accedere al container tramite interfaccia WebSocket + +--- + # 沙箱网关服务 沙箱网关服务提供了HTTP和WebSocket接口，允许客户端创建和管理沙箱Docker容器，并通过WebSocket连接与容器进行通信。 diff --git a/backend/sdk-base/README.md b/backend/sdk-base/README.md index 0d63711a4..85f696cdf 100644 --- a/backend/sdk-base/README.md +++ b/backend/sdk-base/README.md @@ -1,5 +1,22 @@ # sdk-base +## 📦 Installazione + +```shell +$ composer require dtyq/sdk-base -vvv +``` + +## 🚀 Utilizzo + +Vedi dettagli in \Dtyq\SdkBase\Tests\SdkBaseTest + +## 📄 Licenza + +MIT + +--- + +# sdk-base ## Installing @@ -11,7 +28,6 @@ $ composer require dtyq/sdk-base -vvv 详见 \Dtyq\SdkBase\Tests\SdkBaseTest - ## License MIT \ No newline at end of file diff --git a/backend/super-magic/README.md b/backend/super-magic/README.md index fea7fb7a1..aa47f704f 100644 --- a/backend/super-magic/README.md +++ b/backend/super-magic/README.md @@ -1,5 +1,62 @@ # SuperMagic +SuperMagic è il prodotto di punta della matrice di prodotti Magic, un **Sistema di Intelligenza Artificiale Generale (AGI)** progettato specificamente per scenari di task complessi. Attraverso un sistema di design multi-agente e capacità di tool ricchi, supporta capacità intelligenti come **comprensione autonoma dei task**, **pianificazione autonoma dei task**, **azione autonoma** e **correzione autonoma degli errori**. SuperMagic può comprendere istruzioni in linguaggio naturale, eseguire vari processi aziendali e consegnare risultati finali degli obiettivi. + +Come prodotto di punta della matrice di prodotti Magic, SuperMagic fornisce potenti capacità di sviluppo secondario attraverso open source, permettendo alle imprese di costruire e distribuire rapidamente assistenti intelligenti che soddisfano esigenze aziendali specifiche, migliorando significativamente l'efficienza e la qualità delle decisioni. + +## 🛠️ Caratteristiche Principali + +- **🔧 Supporto Multi-Tool**: Pre-carica tool comuni, inclusi esecuzione Python, ricerca web, operazioni browser, operazioni file, ecc. +- **📊 Gestione Stato**: Meccanismo completo di gestione dello stato, supporta stati come IDLE, RUNNING, FINISHED, ERROR, ecc. +- **🎛️ Controllo Esecuzione**: Supporta limitazione del numero massimo di iterazioni e limitazione della lunghezza dell'output +- **🤖 Collaborazione Multi-Agente**: Supporta collaborazione tra molteplici agenti, gestendo scenari di task complessi +- **🔗 Integrazione Seamless**: Integrazione seamless con prodotti della matrice come Magic Flow, realizzando orchestrazione workflow più potente + +## 📋 Requisiti di Installazione + +- Python 3.12+ +- Chiave API del modello di grandi dimensioni (Claude, OpenAI, DeepSeek V3, Qwen) +- Pacchetti di dipendenze correlati + +## ⚙️ Impostazione Variabili Ambiente + +Prima dell'uso, assicurati di aver impostato le variabili ambiente attraverso file `.env` o impostazioni di sistema. + +Variabili ambiente obbligatorie: +- `OPENAI_API_KEY`: Chiave API OpenAI + +## 💼 Casi d'Uso + +SuperMagic può essere applicato a vari scenari aziendali complessi, di seguito alcuni casi tipici: + +- [Analisi delle intuizioni di investimento dell'Assemblea Azionisti 2025 di Warren Buffett](https://www.letsmagic.cn/share/777665156986277889) +- [Analisi delle azioni correlate alla mezza maratona dei robot umanoidi di Pechino](https://www.letsmagic.cn/share/774280936479625217) +- [Riassunto dei concetti core di "Thinking, Fast and Slow"](https://www.letsmagic.cn/share/777461325648195584) +- [Analisi IPO e consigli di investimento di Shanghai Auntie](https://www.letsmagic.cn/share/777604044873928705) +- [Richiesta previsione vendite SKU](https://www.letsmagic.cn/share/771022574397648897) + +Per più casi visita il [sito ufficiale](https://www.letsmagic.cn). + +## 🔗 Progetti Correlati + +SuperMagic è parte della matrice di prodotti Magic, collabora con i seguenti prodotti: + +- **[Magic IM](https://github.com/dtyq/magic)** - Sistema di comunicazione istantanea aziendale che integra agenti AI con comunicazioni interne aziendali +- **[Magic Flow](https://github.com/dtyq/magic-flow)** - Sistema potente di orchestrazione workflow AI visualizzato +- **[Agentlang](https://github.com/dtyq/agentlang)** - Framework agente AI centrato sul linguaggio, utilizzato per costruire agenti AI utilizzando linguaggio naturale + +## 🤝 Contributi e Supporto + +Benvenuti a contribuire codice o proporre suggerimenti per SuperMagic. Se trovate problemi, vi preghiamo di sottoporre issue nel repository GitHub. + +## 📄 Licenza + +Questo progetto segue la [Licenza Open Source Magic](https://github.com/dtyq/magic/blob/main/LICENSE), essenzialmente Apache 2.0 ma con alcune restrizioni aggiuntive. + +--- + +# SuperMagic + SuperMagic 是 Magic 产品矩阵的旗舰产品，是一个专为复杂任务场景设计的**通用人工智能系统(AGI)**。它通过多智能体设计系统和丰富的工具能力，支持**自主任务理解**、**自主任务规划**、**自主行动**以及**自主错误修正**等智能能力。SuperMagic 可以理解自然语言指令，执行各种业务流程，并交付最终目标结果。 作为 Magic 产品矩阵的旗舰产品，SuperMagic 通过开源提供强大的二次开发能力，使企业能够快速构建和部署满足特定业务需求的智能助手，大幅提升决策效率和质量。 diff --git a/backend/super-magic/guides/config_management_guide.md b/backend/super-magic/guides/config_management_guide.md index 35f8d63b9..69a88d9ff 100644 --- a/backend/super-magic/guides/config_management_guide.md +++ b/backend/super-magic/guides/config_management_guide.md @@ -1,3 +1,160 @@ +# Guida alla Gestione della Configurazione SuperMagic + +## Panoramica + +SuperMagic utilizza un sistema di gestione della configurazione flessibile, basato su file YAML e variabili d'ambiente, che supporta la configurazione gerarchica e la validazione dei tipi. Il sistema fornisce un'interfaccia unificata per l'accesso alla configurazione e supporta il caricamento a caldo e l'aggiornamento dinamico della configurazione. + +## Componenti del Sistema di Configurazione + +- **Gestore della Configurazione**: Responsabile del caricamento, dell'analisi e della gestione dei dati di configurazione, supporta molteplici fonti di configurazione +- **Modello di Configurazione**: Utilizza modelli Pydantic per definire la struttura della configurazione e i valori predefiniti +- **File di Configurazione**: File di configurazione principale memorizzato in `config/config.yaml` +- **Variabili d'Ambiente**: Fa riferimento alle variabili d'ambiente del sistema tramite segnaposto, supporta valori predefiniti + +## Struttura del File di Configurazione + +Il file di configurazione principale si trova in `config/config.yaml`, utilizza il formato YAML e contiene le seguenti parti principali: + +- **browser**: Configurazioni relative al browser +- **llm**: Configurazioni generali dell'API LLM +- **agent**: Configurazioni del sistema agente +- **image_generator**: Configurazioni del servizio di generazione immagini +- **models**: Configurazioni di molteplici modelli, inclusi vari modelli LLM + - Ogni modello contiene elementi di configurazione come api_key, api_base_url, name, type, supports_tool_use +- **Configurazioni di Servizio**: Configurazioni dedicate per vari servizi +- **Configurazioni di Sistema**: Configurazioni del sistema core + +## Segnaposto delle Variabili d'Ambiente + +Il file di configurazione supporta due formati di riferimento alle variabili d'ambiente: + +1. `${ENV_VAR}` - Fa riferimento alla variabile d'ambiente, senza valore predefinito +2. `${ENV_VAR:-default}` - Fa riferimento alla variabile d'ambiente, se non esiste utilizza il valore predefinito + +Esempio: +```yaml +browser: + headless: ${BROWSER_HEADLESS:-false} + cookies_file: ${BROWSER_COOKIES_FILE:-.browser/cookies.json} + +models: + gpt-4o: + api_key: "${OPENAI_API_KEY}" + api_base_url: "${OPENAI_API_BASE_URL:-https://api.openai.com/v1}" + name: "${OPENAI_MODEL:-gpt-4o}" +``` + +## Conversione dei Tipi di Dati + +Il sistema di configurazione esegue automaticamente la conversione dei tipi di dati: + +- `"true"` e `"false"` vengono convertiti in valori booleani +- Le stringhe numeriche vengono convertite in interi o numeri in virgola mobile +- Liste e dizionari mantengono la loro struttura + +## Metodo d'Uso + +### Ottenere la Configurazione + +```python +from agentlang.config import config + +# Ottenere un elemento di configurazione specifico +headless = config.get("browser.headless") +api_key = config.get("models.gpt-4o.api_key") + +# Utilizzare valori predefiniti +timeout = config.get("llm.api_timeout", 60) +``` + +### Gestore della Configurazione + +```python +from agentlang.config.config import Config + +# Creare un'istanza del gestore della configurazione +config_manager = Config() + +# Caricare la configurazione +config_manager.load_config("/path/to/config.yaml") + +# Utilizzare il percorso con punto per ottenere la configurazione +api_key = config_manager.get("models.gpt-4o.api_key") +model_name = config_manager.get("models.gpt-4o.name", "default-model") +``` + +### Impostare e Ricaricare la Configurazione + +```python +from agentlang.config import config + +# Impostare il valore della configurazione +config.set("models.gpt-4o.temperature", 0.8) + +# Ricaricare la configurazione (per aggiornamenti runtime delle variabili d'ambiente) +config.reload_config() +``` + +## Percorso di Ricerca della Configurazione + +Il sistema cerca i file di configurazione nel seguente ordine: + +1. Percorso specificato dalla variabile d'ambiente `CONFIG_PATH` +2. `config/config.yaml` nella directory radice del progetto + +## Priorità della Configurazione + +La priorità di caricamento della configurazione va dall'alto al basso: + +1. Configurazione runtime impostata tramite `config.set()` +2. Variabili d'ambiente +3. Valori nel file di configurazione +4. Valori predefiniti nel modello Pydantic + +## Note di Sicurezza + +- Le informazioni sensibili (come le chiavi API) dovrebbero essere fornite tramite variabili d'ambiente o file `.env`, non scritte direttamente nei file di configurazione +- Nei file di configurazione si dovrebbero utilizzare i segnaposto delle variabili d'ambiente per fare riferimento alle informazioni sensibili +- I file `.env` non dovrebbero essere sottoposti a controllo versione +- Seguire le note di sicurezza all'inizio del file di configurazione, non esporre informazioni sensibili nei file di configurazione + +## Integrazione con File .env + +SuperMagic supporta il caricamento delle variabili d'ambiente tramite file `.env`. Per dettagli fare riferimento a [dotenv_configuration.md](dotenv_configuration.md). + +## Domande Frequenti + +### Configurazione non caricata correttamente + +Assicurarsi che: +- Il file di configurazione esista nella posizione corretta +- Le variabili d'ambiente siano impostate correttamente +- Il formato del file di configurazione sia corretto (YAML valido) + +### Variabili d'ambiente non efficaci + +- Verificare che il formato del segnaposto sia corretto +- Confermare che la variabile d'ambiente sia impostata +- Controllare maiuscole/minuscole nel nome della variabile d'ambiente + +### Posizione di configurazione personalizzata + +È possibile specificare un percorso di file di configurazione personalizzato tramite variabile d'ambiente: + +```python +import os +os.environ["CONFIG_PATH"] = "/path/to/custom/config.yaml" + +# Poi caricare la configurazione +from agentlang.config.config import Config +config_manager = Config() +config_manager.load_config() +``` + +--- + +# Original Chinese Content / Contenuto Originale Cinese + # SuperMagic 配置管理指南 ## 概述 diff --git a/backend/super-magic/guides/dotenv_configuration.md b/backend/super-magic/guides/dotenv_configuration.md index 49b2039e8..4ea9aba3b 100644 --- a/backend/super-magic/guides/dotenv_configuration.md +++ b/backend/super-magic/guides/dotenv_configuration.md @@ -1,3 +1,33 @@ +# Configurazione Priorità File .env + +## Panoramica + +Nel progetto viene utilizzata la libreria `python-dotenv` per caricare le variabili d'ambiente. Per impostazione predefinita, questa libreria non sovrascrive le variabili d'ambiente di sistema esistenti. Questa modifica permette al progetto di leggere prioritariamente la configurazione dal file `.env`, anche se le variabili d'ambiente con lo stesso nome esistono già nel sistema. + +## Implementazione Tecnica + +Aggiungendo il parametro `override=True` a tutte le chiamate `load_dotenv()`, è stato implementato che la configurazione nel file `.env` abbia priorità più alta rispetto alle variabili d'ambiente di sistema. + +Sono state modificate le chiamate `load_dotenv()` nei seguenti file: + +1. `main.py` +2. `bin/v6.py` +3. `app/vector_store/example.py` +4. `app/vector_store/examples/collection_prefix_example.py` + +## Metodo d'Uso + +Non è necessario cambiare il metodo d'uso esistente, basta assicurarsi di scrivere le variabili d'ambiente che necessitano di essere sovrascritte nel file `.env`. Queste configurazioni sovrascriveranno le variabili d'ambiente con lo stesso nome esistenti nel sistema. + +## Note + +- Se in scenari specifici è necessario ripristinare il comportamento originale (senza sovrascrivere le variabili d'ambiente di sistema), è possibile impostare temporaneamente il parametro `override` della chiamata `load_dotenv()` corrispondente su `False`. +- Questa modifica è particolarmente applicabile agli ambienti di sviluppo e test, permettendo di cambiare facilmente diverse configurazioni senza modificare le variabili d'ambiente di sistema. + +--- + +# Original Chinese Content / Contenuto Originale Cinese + # .env 文件优先级配置 ## 概述 diff --git a/backend/super-magic/guides/event_system_guide.md b/backend/super-magic/guides/event_system_guide.md index 1e36eb284..0c597f3c0 100644 --- a/backend/super-magic/guides/event_system_guide.md +++ b/backend/super-magic/guides/event_system_guide.md @@ -1,3 +1,263 @@ +# Guida all'Architettura del Sistema di Eventi SuperMagic + +## Panoramica + +Il sistema di eventi SuperMagic è un'architettura basata su modello publish-subscribe per l'evento-driven, utilizzata durante l'esecuzione dell'Agent per implementare il disaccoppiamento e la comunicazione tra vari componenti. Il sistema di eventi è diviso in due livelli: + +1. **Livello Base (agentlang)**: Fornisce la definizione dei tipi di eventi core e il meccanismo di distribuzione degli eventi +2. **Livello Applicazione (app)**: Fornisce l'implementazione degli eventi business specifici e i servizi listener + +Questo sistema di eventi permette a SuperMagic di realizzare un design modulare altamente scalabile, dove i listener possono rispondere a vari eventi nel ciclo di vita dell'Agent, come operazioni sui file, completamento dei task, interazioni con modelli di grandi dimensioni, ecc. + +## 1. Architettura Base del Sistema di Eventi (agentlang) + +### 1.1 Tipi di Eventi Core (EventType) + +`agentlang/event/event.py` definisce tutti i tipi di eventi supportati dal sistema: + +```python +class EventType(str, Enum): + """Enumerazione dei tipi di eventi""" + # Eventi del ciclo di vita dell'Agent + BEFORE_INIT = "before_init" # Evento prima dell'inizializzazione + AFTER_INIT = "after_init" # Evento dopo l'inizializzazione + AGENT_SUSPENDED = "agent_suspended" # Evento di terminazione agent + MAIN_AGENT_FINISHED = "main_agent_finished" # Evento di completamento esecuzione agent principale + + # Eventi di controllo sicurezza + BEFORE_SAFETY_CHECK = "before_safety_check" # Evento prima del controllo sicurezza + AFTER_SAFETY_CHECK = "after_safety_check" # Evento dopo il controllo sicurezza + + # Eventi di interazione utente + AFTER_CLIENT_CHAT = "after_client_chat" # Evento dopo la chat del client + + # Eventi di interazione con modelli di grandi dimensioni + BEFORE_LLM_REQUEST = "before_llm_request" # Evento prima della richiesta al modello di grandi dimensioni + AFTER_LLM_REQUEST = "after_llm_request" # Evento dopo la richiesta al modello di grandi dimensioni + + # Eventi di chiamata strumento + BEFORE_TOOL_CALL = "before_tool_call" # Evento prima della chiamata strumento + AFTER_TOOL_CALL = "after_tool_call" # Evento dopo la chiamata strumento + + # Eventi di operazione file + FILE_CREATED = "file_created" # Evento di creazione file + FILE_UPDATED = "file_updated" # Evento di aggiornamento file + FILE_DELETED = "file_deleted" # Evento di eliminazione file + + # Eventi di gestione errori + ERROR = "error" # Evento di errore +``` + +### 1.2 Classe Base Evento (Event) + +La classe base evento definisce la struttura base dell'evento: + +```python +class Event(Generic[T]): + def __init__(self, event_type: EventType, data: BaseEventData): + self._event_type = event_type + self._data = data + + @property + def event_type(self) -> EventType: + return self._event_type + + @property + def data(self) -> T: + return self._data +``` + +### 1.3 Evento Arrestabile (StoppableEvent) + +Alcuni eventi possono interrompere il flusso di propagazione: + +```python +class StoppableEvent(Event[T]): + def __init__(self, event_type: EventType, data: BaseEventData): + super().__init__(event_type, data) + self._propagation_stopped = False + + def stop_propagation(self) -> None: + self._propagation_stopped = True + + def is_propagation_stopped(self) -> bool: + return self._propagation_stopped +``` + +### 1.4 Dispatcher degli Eventi (EventDispatcher) + +`EventDispatcher` è responsabile della registrazione e distribuzione degli eventi: + +```python +# In agentlang/event/dispatcher.py +class EventDispatcher: + def __init__(self): + self._listeners = defaultdict(list) + + def add_listener(self, event_type: EventType, listener: Callable[[Event[Any]], None]) -> None: + self._listeners[event_type].append(listener) + + async def dispatch(self, event_type: EventType, data: BaseEventData) -> Event[Any]: + event = Event(event_type, data) + for listener in self._listeners.get(event_type, []): + await asyncio.ensure_future(listener(event)) + return event + + async def dispatch_stoppable(self, event_type: EventType, data: BaseEventData) -> StoppableEvent[Any]: + event = StoppableEvent(event_type, data) + for listener in self._listeners.get(event_type, []): + if event.is_propagation_stopped(): + break + await asyncio.ensure_future(listener(event)) + return event +``` + +## 2. Sistema di Eventi del Livello Applicazione (app) + +### 2.1 Strutture Dati degli Eventi + +Il livello applicazione definisce le strutture dati degli eventi specifici in `app/core/entity/event/event.py`: + +```python +# Di seguito alcuni esempi di strutture dati eventi chiave: +class BeforeLlmRequestEventData(BaseEventData): + """Struttura dati evento prima della richiesta al modello di grandi dimensioni""" + model_name: str + chat_history: List[Dict[str, Any]] + tools: Optional[List[Dict[str, Any]]] = None + tool_context: ToolContext + +class AfterLlmResponseEventData(BaseEventData): + """Struttura dati evento dopo la richiesta al modello di grandi dimensioni""" + model_name: str + request_time: float + success: bool + error: Optional[str] = None + tool_context: ToolContext + llm_response_message: ChatCompletionMessage + show_in_ui: bool = True +``` + +### 2.2 Classe Base Servizio Listener + +Tutti i servizi listener ereditano da `BaseListenerService`, fornendo la logica di registrazione eventi generica: + +```python +class BaseListenerService: + @staticmethod + def register_event_listener(agent_context: AgentContext, event_type: EventType, + listener: Callable[[Event[Any]], None]) -> None: + agent_context.add_event_listener(event_type, listener) + + @staticmethod + def register_listeners(agent_context: AgentContext, + event_listeners: Dict[EventType, Callable[[Event[Any]], None]]) -> None: + for event_type, listener in event_listeners.items(): + BaseListenerService.register_event_listener(agent_context, event_type, listener) +``` + +### 2.3 Meccanismo di Registrazione Listener + +Nel metodo `setup` di `AgentDispatcher` vengono registrati uniformemente vari listener: + +```python +async def setup(self): + """Imposta il contesto Agent e registra i listener""" + self.agent_context = self.agent_service.create_agent_context( + stream_mode=False, + task_id="", + streams=[StdoutStream()], + is_main_agent=True, + sandbox_id=str(config.get("sandbox.id")) + ) + + # Registra vari listener + FileStorageListenerService.register_standard_listeners(self.agent_context) + TodoListenerService.register_standard_listeners(self.agent_context) + FinishTaskListenerService.register_standard_listeners(self.agent_context) + StreamListenerService.register_standard_listeners(self.agent_context) + RagListenerService.register_standard_listeners(self.agent_context) + FileListenerService.register_standard_listeners(self.agent_context) + CostLimitListenerService.register_standard_listeners(self.agent_context) +``` + +### 2.4 Implementazione Servizi Listener Specifici + +Ogni servizio listener implementa la funzionalità corrispondente, prendendo come esempio `FileStorageListenerService`: + +```python +class FileStorageListenerService: + @staticmethod + def register_standard_listeners(agent_context: AgentContext) -> None: + # Crea la mappatura da tipo evento a funzione di gestione + event_listeners = { + EventType.FILE_CREATED: FileStorageListenerService._handle_file_event, + EventType.FILE_UPDATED: FileStorageListenerService._handle_file_event, + EventType.FILE_DELETED: FileStorageListenerService._handle_file_deleted, + EventType.MAIN_AGENT_FINISHED: FileStorageListenerService._handle_main_agent_finished + } + + # Utilizza il metodo della classe base per registrare in batch i listener + BaseListenerService.register_listeners(agent_context, event_listeners) + + @staticmethod + async def _handle_file_event(event: Event[FileEventData]) -> None: + # Implementazione della gestione degli eventi di creazione e aggiornamento file... +``` + +## 3. Supporto Eventi in Agent Context + +La classe `AgentContext` fornisce le funzionalità core del meccanismo eventi: + +```python +class AgentContext(BaseContext, AgentContextInterface): + def add_event_listener(self, event_type: EventType, listener: Callable[[Event[Any]], None]) -> None: + """Aggiunge un listener di eventi""" + self.agent_common_context._event_dispatcher.add_listener(event_type, listener) + + async def dispatch_event(self, event_type: EventType, data: BaseEventData) -> Event[Any]: + """Distribuisce l'evento""" + return await self.agent_common_context._event_dispatcher.dispatch(event_type, data) + + async def dispatch_stoppable_event(self, event_type: EventType, data: BaseEventData) -> StoppableEvent[Any]: + """Distribuisce l'evento arrestabile""" + return await self.agent_common_context._event_dispatcher.dispatch_stoppable(event_type, data) +``` + +## 4. Panoramica Funzionalità Principali Servizi Listener + +SuperMagic contiene molteplici servizi listener, ognuno responsabile della gestione di tipi specifici di eventi: + +| Servizio Listener | Funzionalità Principali | +|-------------------|-------------------------| +| FileStorageListenerService | Gestisce eventi file, carica file al servizio di storage | +| TodoListenerService | Gestisce aggiunta, aggiornamento ed eliminazione dei task in sospeso | +| FinishTaskListenerService | Gestisce eventi di completamento task, esegue pulizie successive | +| StreamListenerService | Gestisce eventi di output streaming, invia messaggi al client | +| RagListenerService | Gestisce eventi relativi alla generazione aumentata di retrieval | +| FileListenerService | Gestisce monitoraggio cambiamenti del file system | +| CostLimitListenerService | Monitora e limita il costo delle chiamate API | + +## 5. Estensione del Sistema di Eventi + +Per aggiungere nuova gestione eventi, si consiglia di seguire questi passi: + +1. Se necessario un nuovo tipo di evento, aggiungere nell'enumerazione `EventType` in `agentlang/event/event.py` +2. Definire la struttura dati evento corrispondente in `app/core/entity/event/event.py` +3. Creare una nuova classe servizio listener, ereditando o facendo riferimento a `BaseListenerService` +4. Implementare il metodo di gestione eventi +5. Registrare il nuovo servizio listener in `AgentDispatcher.setup()` + +## Conclusione + +Il sistema di eventi SuperMagic fornisce un modo flessibile ed estensibile per gestire vari cambiamenti di stato e interazioni nel sistema. Attraverso l'architettura event-driven, i vari componenti possono comunicare senza un accoppiamento stretto, rendendo il sistema più modulare e manutenibile. + +Il design a livelli del sistema di eventi (agentlang fornisce le basi, app fornisce l'implementazione business) riflette anche la buona pratica architettonica della separazione delle preoccupazioni, rendendo il sistema più facile da comprendere ed estendere. + +--- + +# Original Chinese Content / Contenuto Originale Cinese + # SuperMagic 事件系统架构指南 ## 概述 diff --git a/backend/super-magic/guides/super_magic.md b/backend/super-magic/guides/super_magic.md index a2a5870f5..c226e35f0 100644 --- a/backend/super-magic/guides/super_magic.md +++ b/backend/super-magic/guides/super_magic.md @@ -1,3 +1,313 @@ +# Documentazione Dettagliata della Classe SuperMagic + +SuperMagic è la classe agente (Agent) principale del progetto, che integra le funzionalità chiave dell'agente intelligente. È responsabile della gestione delle query degli utenti, della chiamata ai modelli di linguaggio di grandi dimensioni, dell'esecuzione degli strumenti, della gestione dello stato e della coordinazione di varie risorse. Questo documento analizza in dettaglio il design, l'implementazione e il flusso di lavoro della classe SuperMagic. + +## Panoramica delle Funzionalità Principali + +SuperMagic implementa un sistema agente AI completo, le cui principali funzionalità includono: + +1. Interazione con i modelli di linguaggio di grandi dimensioni (LLM) +2. Gestione e esecuzione delle chiamate agli strumenti +3. Gestione della cronologia delle chat +4. Sistema di eventi e gestione dei callback +5. Elaborazione dinamica dei prompt +6. Gestione dello stato dell'agente +7. Gestione del ciclo di vita delle risorse + +## Componenti Chiave + +La classe SuperMagic collabora strettamente con molteplici componenti: + +- **LLMAdapter**: Responsabile dell'interazione con i modelli di linguaggio di grandi dimensioni (come GPT-4, ecc.) +- **ToolExecutor**: Esegue varie chiamate agli strumenti +- **PromptProcessor**: Elabora i prompt di sistema +- **AgentContext**: Mantiene il contesto di esecuzione dell'agente +- **ToolCollection**: Gestisce la collezione di strumenti disponibili + +## Flusso di Lavoro + +Il flusso di lavoro principale di SuperMagic si divide nei seguenti passaggi: + +1. **Inizializzazione**: Carica la configurazione, inizializza i componenti +2. **Ricezione della query utente**: Elabora l'input dell'utente +3. **Esecuzione ciclica**: Invia continuamente richieste all'LLM, analizza le chiamate agli strumenti nelle risposte ed esegue +4. **Completamento del compito**: Termina quando viene rilevato il completamento del compito o viene raggiunto il numero massimo di iterazioni + +### Flusso di Esecuzione Dettagliato + +``` +Query utente -> Inizializzazione ambiente -> Impostazione stato su RUNNING +-> Ciclo{ + Verifica se è necessario sostituire la cronologia chat + -> Invio richiesta all'LLM + -> Analisi delle chiamate agli strumenti nella risposta LLM + -> Esecuzione delle chiamate agli strumenti + -> Elaborazione dei risultati degli strumenti + -> Verifica se il compito è completato +} +-> Pulizia risorse -> Restituzione risultato +``` + +## Spiegazione Dettagliata dei Metodi Principali + +### Metodi di Inizializzazione e Configurazione + +#### `__init__` +- **Scopo**: Inizializza l'istanza SuperMagic +- **Punti implementativi chiave**: + - Inizializza stato, esecutore strumenti, adattatore LLM + - Imposta il flag dei prompt dinamici + - Inizializza il contatore di token + - Inizializza vari callback + - Stabilisce la directory di lavoro + - Sincronizza la configurazione da agent_context + - Registra il callback di completamento compito + +#### `set_context` +- **Scopo**: Imposta il contesto dell'agente +- **Metodi collegati**: `_initialize_history_manager_from_context`, `_update_file_tools_base_dir` +- **Punti implementativi chiave**: + - Riceve l'oggetto AgentContext + - Sincronizza le impostazioni del modello, le impostazioni della modalità streaming e le impostazioni dei prompt dinamici + - Inizializza il gestore della cronologia + +#### `set_agent` +- **Scopo**: Imposta l'agente da utilizzare e il corrispondente prompt +- **Metodi collegati**: `_setup_agent_and_model` +- **Punti implementativi chiave**: + - Imposta il nome dell'agente + - Aggiorna il nome dell'agente nel gestore della cronologia chat + - Utilizza il modello specificato nel file agent + +#### `set_llm_model` +- **Scopo**: Imposta il modello LLM +- **Punti implementativi chiave**: + - Tenta di impostare il modello predefinito dell'adattatore LLM + - Aggiorna il nome del modello corrente + +### Metodi di Gestione degli Strumenti + +#### `load_tools_by_config` +- **Scopo**: Carica gli strumenti specificati secondo la configurazione degli strumenti +- **Metodi collegati**: `_initialize_available_tools`, `register_tool` +- **Punti implementativi chiave**: + - Svuota la collezione di strumenti corrente + - Verifica la validità dei nomi degli strumenti + - Carica e registra gli strumenti specificati + - Aggiorna la collezione di strumenti dell'esecutore strumenti + +#### `_initialize_available_tools` +- **Scopo**: Inizializza la lista delle istanze di strumenti disponibili +- **Punti implementativi chiave**: + - Ottiene tutte le istanze di strumenti disponibili dal registro degli strumenti + - Aggiorna la lista di tutte le istanze di strumenti disponibili + - Imposta la directory di base per gli strumenti limitati ai confini del workspace + +#### `register_tool` +- **Scopo**: Registra uno strumento +- **Punti implementativi chiave**: + - Aggiunge lo strumento alla collezione di strumenti + - Gestisce gli strumenti che necessitano di risorse speciali + - Imposta il riferimento dell'agente per lo strumento + - Aggiorna la collezione di strumenti dell'esecutore strumenti + +### Metodi del Flusso di Esecuzione + +#### `run` +- **Scopo**: Esegue l'agente SuperMagic, elabora la query dell'utente +- **Metodi collegati**: `run_async` +- **Punti implementativi chiave**: + - Crea un ciclo di eventi + - Chiama il metodo di esecuzione asincrona + - Gestisce l'interruzione da tastiera + +#### `run_async` +- **Scopo**: Esegue l'agente in modo asincrono +- **Metodi collegati**: `_initialize_agent_environment`, `_get_next_function_call_response`, `_parse_tool_calls`, `_execute_tool_calls`, `_process_tool_results`, `_cleanup_resources` +- **Punti implementativi chiave**: + - Inizializza l'ambiente dell'agente e la cronologia chat + - Imposta lo stato su in esecuzione + - Entra nel ciclo principale: + - Ottiene la descrizione degli strumenti + - Verifica se il modello supporta le chiamate agli strumenti + - Ottiene la risposta LLM + - Analizza le chiamate agli strumenti + - Esegue le chiamate agli strumenti + - Elabora i risultati degli strumenti + - Verifica se il compito è completato + - Elabora il risultato finale + - Pulisce le risorse + +#### `_initialize_agent_environment` +- **Scopo**: Inizializza l'ambiente dell'agente e la cronologia chat +- **Metodi collegati**: `set_context`, `_initialize_history_manager_from_context`, `_setup_agent_and_model`, `_update_file_tools_base_dir` +- **Punti implementativi chiave**: + - Imposta il contesto + - Inizializza il gestore della cronologia + - Imposta l'agente e il modello + - Verifica se il modello supporta le chiamate agli strumenti + - Aggiorna la directory di lavoro + - Imposta il prompt di sistema + - Carica la cronologia chat + - Verifica se è necessario comprimere la cronologia chat + +#### `_get_next_function_call_response` +- **Scopo**: Ottiene la prossima risposta contenente chiamate di funzione dall'LLM +- **Metodi collegati**: `_create_api_error_response` +- **Punti implementativi chiave**: + - Attiva l'evento prima della richiesta LLM + - Ottiene la risposta dall'adattatore LLM + - Attiva l'evento dopo la richiesta LLM + - Verifica la risposta + +### Metodi di Esecuzione degli Strumenti + +#### `_execute_tool_calls` +- **Scopo**: Esegue le chiamate agli strumenti +- **Metodi collegati**: Nessuno diretto, ma interagisce con l'esecutore strumenti +- **Punti implementativi chiave**: + - Itera attraverso la lista delle chiamate agli strumenti + - Ottiene il nome dello strumento e i parametri + - Attiva l'evento prima della chiamata allo strumento + - Esegue lo strumento + - Attiva l'evento dopo la chiamata allo strumento + +#### `_process_tool_results` +- **Scopo**: Elabora i risultati dell'esecuzione degli strumenti e li aggiunge alla cronologia chat +- **Metodi collegati**: `_save_chat_history` +- **Punti implementativi chiave**: + - Aggiunge i risultati dell'esecuzione degli strumenti alla cronologia chat + - Elabora istruzioni di sistema speciali (come FINISH_TASK) + - Verifica se è lo strumento ask_user e contiene l'istruzione di sistema ASK_USER + - Salva la cronologia chat + +### Metodi di Gestione dei Messaggi e della Cronologia + +#### `_save_chat_history` +- **Scopo**: Salva la cronologia chat su file +- **Punti implementativi chiave**: + - Verifica se il gestore della cronologia è inizializzato + - Chiama il metodo di salvataggio del gestore della cronologia + - Registra il risultato del salvataggio + +#### `_load_chat_history` +- **Scopo**: Carica la cronologia chat dal file +- **Punti implementativi chiave**: + - Verifica se il gestore della cronologia è inizializzato + - Chiama il metodo di caricamento del gestore della cronologia + - Registra il numero di record storici caricati + +#### `_parse_tool_calls` +- **Scopo**: Analizza le chiamate agli strumenti dalla risposta del modello +- **Punti implementativi chiave**: + - Analizza le chiamate agli strumenti nella risposta OpenAI + - Restituisce la lista delle chiamate agli strumenti + +#### `_parse_tool_content` +- **Scopo**: Analizza il contenuto delle chiamate agli strumenti, lo converte in oggetti chiamata strumento +- **Punti implementativi chiave**: + - Tenta molteplici modalità di matching delle chiamate agli strumenti + - Gestisce il formato di chiamata diretta + - Gestisce il formato JSON + - Gestisce il formato di chiamata in stile Python + +### Metodi di Gestione e Pulizia delle Risorse + +#### `_cleanup_resources` +- **Scopo**: Pulisce tutte le risorse attive +- **Punti implementativi chiave**: + - Itera attraverso il dizionario active_resources + - Chiama il metodo cleanup per ogni risorsa + - Registra il processo di pulizia + +#### `_on_finish_task` +- **Scopo**: Funzione di callback quando lo strumento di completamento compito viene eseguito con successo +- **Punti implementativi chiave**: + - Imposta lo stato dell'agente su completato + - Output del log + +### Metodi per Gestire Situazioni Speciali + +#### `_handle_non_tool_model_response` +- **Scopo**: Gestisce la risposta di modelli che non supportano le chiamate agli strumenti +- **Metodi collegati**: `_save_chat_history`, `_trigger_assistant_message`, `_on_finish_task` +- **Punti implementativi chiave**: + - Registra la risposta dell'assistente + - Salva la cronologia chat + - Attiva l'evento di messaggio assistente + - Chiama il callback di completamento compito + +#### `_handle_potential_loop` +- **Scopo**: Gestisce situazioni di potenziale loop infinito +- **Metodi collegati**: `_save_chat_history` +- **Punti implementativi chiave**: + - Registra il log di avviso + - Aggiorna la cronologia chat + - Determina la risposta finale + - Imposta lo stato su completato + +## Gestione dello Stato + +SuperMagic utilizza l'enumerazione AgentState per gestire lo stato dell'agente: + +- **IDLE**: Stato di inattività +- **RUNNING**: In esecuzione +- **FINISHED**: Completato +- **ERROR**: Stato di errore +- **INIT**: Stato di inizializzazione + +Relazioni di transizione di stato: +``` +INIT -> IDLE -> RUNNING -> [FINISHED | ERROR] +``` + +## Sistema di Eventi + +SuperMagic implementa un sistema di eventi che permette di attivare eventi in punti chiave: + +- **BEFORE_LLM_REQUEST**: Prima dell'invio della richiesta LLM +- **AFTER_LLM_REQUEST**: Dopo la ricezione della risposta LLM +- **BEFORE_TOOL_CALL**: Prima dell'esecuzione della chiamata allo strumento +- **AFTER_TOOL_CALL**: Dopo l'esecuzione della chiamata allo strumento + +## Punti di Integrazione ed Estensione + +SuperMagic fornisce molteplici punti di estensione: + +1. **Sistema di Strumenti**: Implementando l'interfaccia BaseTool è possibile aggiungere facilmente nuovi strumenti +2. **Adattamento del Modello**: Tramite LLMAdapter è possibile supportare diversi modelli di linguaggio di grandi dimensioni +3. **Callback degli Eventi**: Tramite il sistema di eventi è possibile aggiungere logica personalizzata in punti chiave +4. **Elaborazione dei Prompt**: È possibile personalizzare il comportamento dell'agente tramite il sistema di prompt dinamici + +## Esempio di Flusso di Applicazione Pratica + +Di seguito un esempio tipico di flusso di esecuzione: + +1. L'utente invia una query: "Trova le ultime ricerche sul cambiamento climatico" +2. SuperMagic inizializza l'ambiente, imposta lo stato su RUNNING +3. Invia la richiesta all'LLM, ottiene una risposta contenente chiamate agli strumenti +4. L'LLM suggerisce di utilizzare lo strumento "bing_search" per cercare le ultime ricerche +5. SuperMagic esegue lo strumento "bing_search" +6. Aggiunge i risultati della ricerca alla cronologia chat +7. Continua a inviare richieste all'LLM, includendo i risultati della ricerca +8. L'LLM potrebbe suggerire di utilizzare lo strumento "browser_use" per accedere a pagine web specifiche +9. SuperMagic esegue lo strumento "browser_use" +10. Il ciclo continua fino a quando l'LLM chiama lo strumento "finish_task" o viene raggiunto il numero massimo di iterazioni +11. SuperMagic pulisce le risorse, restituisce il risultato finale + +## Migliori Pratiche e Note di Attenzione + +1. **Gestione delle Risorse**: Assicurarsi che tutte le risorse che necessitano di pulizia siano correttamente registrate in active_resources +2. **Gestione degli Errori**: Tutte le esecuzioni degli strumenti dovrebbero catturare e gestire le eccezioni per evitare l'interruzione dell'intero flusso dell'agente +3. **Tracciamento dello Stato**: Tracciare correttamente il ciclo di vita dell'agente tramite il sistema di stati +4. **Compatibilità del Modello**: Diversi modelli hanno diversi livelli di supporto per le chiamate agli strumenti, necessitano di una gestione appropriata + +## Riepilogo + +La classe SuperMagic è il componente principale del progetto, coordina molteplici sottosistemi per implementare un agente AI completo nelle funzionalità. Il suo design considera l'estensibilità, la robustezza e le prestazioni, ed è in grado di gestire query utente complesse ed eseguire compiti multi-step. + +--- + # SuperMagic 类详细文档 SuperMagic是项目的核心代理(Agent)类，整合了智能代理的关键功能。它负责处理用户查询、调用大语言模型、执行工具、管理状态、以及协调各种资源。本文档详细解析SuperMagic类的设计、实现与工作流程。 diff --git a/backend/super-magic/guides/tools_architecture_guide.md b/backend/super-magic/guides/tools_architecture_guide.md index 21752532c..d930fdb9f 100644 --- a/backend/super-magic/guides/tools_architecture_guide.md +++ b/backend/super-magic/guides/tools_architecture_guide.md @@ -1,3 +1,381 @@ +# Guida all'Architettura del Sistema di Strumenti + +Questo documento fornisce una descrizione dettagliata dell'architettura del sistema di strumenti SuperMagic, inclusi i principi di design, i componenti core, i metodi di sviluppo degli strumenti e le migliori pratiche. + +## 1. Panoramica dell'Architettura + +Il sistema di strumenti adotta un design modulare, composto principalmente dai seguenti componenti core: + +- **BaseTool**: Classe base degli strumenti, tutti gli strumenti ereditano da questa classe +- **BaseToolParams**: Classe base dei parametri degli strumenti, tutte le classi di parametri ereditano da questa classe +- **tool_factory**: Factory singleton degli strumenti, responsabile della scansione, registrazione e istanziazione degli strumenti +- **tool_executor**: Esecutore singleton degli strumenti, responsabile dell'esecuzione degli strumenti e della gestione degli errori +- **@tool()**: Decoratore degli strumenti, utilizzato per la registrazione automatica delle classi di strumenti +- **ToolContext**: Contesto degli strumenti, contiene le informazioni ambientali dell'esecuzione degli strumenti +- **ToolResult**: Risultato degli strumenti, contiene le informazioni del risultato dell'esecuzione degli strumenti + +### 1.1 Diagramma dell'Architettura + +``` + ┌────────────────┐ + │ @tool() │ + │ Decoratore │ + └───────┬────────┘ + │ + ▼ +┌────────────────┐ ┌───────────────┐ ┌────────────────┐ +│ BaseToolParams │◄────────┤ BaseTool │────────►│ ToolResult │ +└────────────────┘ └───────┬───────┘ └────────────────┘ + │ + │ + ┌────────────────┴────────────────┐ + │ │ + ▼ ▼ + ┌────────────────┐ ┌───────────────────┐ + │ tool_factory │◄────────────────┤ tool_executor │ + └────────────────┘ └───────────────────┘ + ▲ ▲ + │ │ + └────────────────┬────────────────┘ + │ + ▼ +┌────────────────┐ ┌──────────────────────┐ +│ ToolContext │────────►│ Implementazione │ +└────────────────┘ │ strumento concreta │ + │ (ListDir, ReadFile) │ + └──────────────────────┘ +``` + +### 1.2 Principi di Design + +1. **Singola Responsabilità**: Ogni strumento è responsabile di una singola funzionalità, la factory gestisce, l'esecutore esegue +2. **Iniezione delle Dipendenze**: Passare le dipendenze attraverso costruttore e contesto, evitare relazioni di dipendenza hardcoded +3. **Sicurezza dei Tipi**: Utilizzare modelli Pydantic per garantire la sicurezza e validazione dei tipi dei parametri +4. **Registrazione Automatica**: Utilizzare decoratori per implementare la registrazione automatica degli strumenti, ridurre il codice di registrazione manuale +5. **Isolamento degli Errori**: Catturare e gestire gli errori di esecuzione degli strumenti, evitare di influenzare il flusso principale +6. **Errori User-Friendly**: Fornire messaggi di errore dettagliati e contesto, facilitare il debugging e la risoluzione dei problemi + +## 2. Componenti Core + +### 2.1 Classe Base degli Strumenti (BaseTool) + +Tutti gli strumenti devono ereditare dalla classe base `BaseTool`, che fornisce l'interfaccia e l'implementazione base degli strumenti. + +```python +class BaseTool(ABC, Generic[T]): + """Classe base degli strumenti""" + # Metadati dello strumento + name: str = "" + description: str = "" + + # Tipo di modello dei parametri + params_class: Type[T] = None + + @abstractmethod + async def execute(self, tool_context: ToolContext, params: T) -> ToolResult: + """Eseguire strumento, sottoclasse deve implementare""" + pass + + async def __call__(self, tool_context: ToolContext, **kwargs) -> ToolResult: + """Punto di ingresso della chiamata dello strumento, gestisce logica generica come conversione parametri""" + # ...gestisce conversione parametri e cattura errori + return result +``` + +Caratteristiche principali della classe `BaseTool`: +- Utilizza generici per supportare modelli di parametri tipizzati +- Il metodo astratto `execute` deve essere implementato dalla sottoclasse +- Il metodo `__call__` fornisce un punto di ingresso unificato, gestisce validazione parametri e cattura errori +- Fornisce meccanismo di generazione di messaggi di errore user-friendly + +### 2.2 Classe Base dei Parametri degli Strumenti (BaseToolParams) + +I parametri degli strumenti devono ereditare dalla classe base `BaseToolParams`, che fornisce i campi base e le regole di validazione dei parametri. + +```python +class BaseToolParams(BaseModel): + """Classe base dei parametri degli strumenti""" + explanation: str = Field( + "", + description="Explain why you're using this tool in first person - briefly state your purpose, expected outcome, and how you'll use the results to help the user." + ) + + @classmethod + def get_custom_error_message(cls, field_name: str, error_type: str) -> Optional[str]: + """Ottenere messaggio di errore parametri personalizzato""" + return None +``` + +Caratteristiche principali della classe `BaseToolParams`: +- Eredita da `BaseModel` di Pydantic, supporta validazione parametri e conversione tipi +- Contiene campo `explanation`, utilizzato per spiegare lo scopo della chiamata dello strumento +- Fornisce meccanismo di messaggi di errore personalizzati, le sottoclassi possono fornire messaggi user-friendly per campi e tipi di errore specifici + +### 2.3 Decoratore degli Strumenti (@tool) + +Il decoratore degli strumenti è utilizzato per la registrazione automatica delle classi di strumenti, semplificando la definizione e gestione degli strumenti. + +```python +@tool() +class MyTool(BaseTool): + """Descrizione del mio strumento""" + # Implementazione strumento... +``` + +Funzionalità principali del decoratore `@tool()`: +- Genera automaticamente il nome dello strumento dal nome della classe (convertito in snake_case) +- Estrae la descrizione dello strumento dalla docstring +- Marca gli attributi dello strumento, facilita la scansione e registrazione da parte della factory degli strumenti +- Associa automaticamente il nome della classe al nome del file corrispondente + +### 2.4 Factory degli Strumenti (tool_factory) + +La factory degli strumenti è responsabile della scoperta automatica, registrazione e istanziazione degli strumenti. Utilizza il pattern singleton per garantire consistenza globale. + +```python +# Utilizzare la factory degli strumenti per ottenere istanza strumento +from app.tools.core.tool_factory import tool_factory + +tool_instance = tool_factory.get_tool_instance("list_dir") + +# Ottenere tutti i nomi degli strumenti +tool_names = tool_factory.get_tool_names() + +# Inizializzare factory (generalmente non necessario chiamare manualmente) +tool_factory.initialize() +``` + +Funzionalità principali di `tool_factory`: +- Scansiona e scopre automaticamente tutte le classi di strumenti nel package `app.tools` +- Registra gli strumenti e memorizza nella cache le informazioni degli strumenti +- Crea istanze degli strumenti e le memorizza nella cache +- Fornisce interfaccia di query delle informazioni degli strumenti + +### 2.5 Esecutore degli Strumenti (tool_executor) + +L'esecutore degli strumenti è responsabile dell'esecuzione degli strumenti e della gestione degli errori. Utilizza anche il pattern singleton per garantire consistenza globale. + +```python +# Utilizzare l'esecutore degli strumenti per eseguire strumento +from app.tools.core.tool_executor import tool_executor + +result = await tool_executor.execute_tool_call(tool_context, arguments) + +# Ottenere istanza strumento +tool = tool_executor.get_tool("list_dir") + +# Ottenere tutti gli schemi delle funzioni di chiamata degli strumenti +schemas = tool_executor.get_tool_schemas() +``` + +Funzionalità principali di `tool_executor`: +- Esegue chiamate di strumenti, inclusa gestione parametri e cattura errori +- Fornisce meccanismo di gestione errori user-friendly +- Ottiene istanze strumenti e informazioni schemi +- Timing delle prestazioni e registrazione log + +### 2.6 Contesto degli Strumenti (ToolContext) + +Il contesto degli strumenti contiene le informazioni ambientali dell'esecuzione degli strumenti, come nome strumento, ID chiamata e altri metadati. + +```python +# Creare contesto strumento +from agentlang.context.tool_context import ToolContext + +tool_context = ToolContext( + tool_name="list_dir", + tool_call_id="some-id", + # Altre informazioni contesto... +) +``` + +### 2.7 Risultato degli Strumenti (ToolResult) + +Il risultato degli strumenti contiene le informazioni del risultato dell'esecuzione degli strumenti, come contenuto, errore, tempo di esecuzione, ecc. + +```python +# Creare risultato strumento +from app.core.entity.tool.tool_result import ToolResult + +result = ToolResult( + content="Risultato esecuzione strumento", + error=None, + name="list_dir", + execution_time=0.1 +) +``` + +## 3. Guida allo Sviluppo degli Strumenti + +### 3.1 Definire Parametri degli Strumenti + +Prima definire la classe dei parametri degli strumenti, ereditando da `BaseToolParams`: + +```python +from pydantic import Field +from app.tools.core import BaseToolParams + +class MyToolParams(BaseToolParams): + """Parametri strumento""" + param1: str = Field(..., description="Descrizione del parametro 1") + param2: int = Field(10, description="Descrizione del parametro 2") + param3: bool = Field(False, description="Descrizione del parametro 3") + + @classmethod + def get_custom_error_message(cls, field_name: str, error_type: str) -> Optional[str]: + """Ottenere messaggio di errore parametri personalizzato""" + if field_name == "param1" and error_type == "missing": + return "param1 è un parametro obbligatorio, fornire un valore stringa" + return None +``` + +Suggerimenti per la definizione dei parametri: +- Utilizzare `Field` di Pydantic per aggiungere descrizioni dettagliate a ogni parametro +- Fornire valori predefiniti ragionevoli per parametri opzionali +- Utilizzare annotazioni di tipo per specificare il tipo dei parametri +- Fornire messaggi di errore user-friendly attraverso `get_custom_error_message` + +### 3.2 Definire Classe Strumento + +Poi definire la classe strumento, ereditando da `BaseTool`, utilizzando il decoratore `@tool()` per la registrazione: + +```python +from app.tools.core import BaseTool, tool +from agentlang.context.tool_context import ToolContext +from app.core.entity.tool.tool_result import ToolResult + +@tool() +class MyTool(BaseTool): + """Descrizione del mio strumento + + Qui la descrizione dettagliata dello strumento, la prima riga verrà estratta automaticamente come descrizione breve. + """ + + # Impostare tipo parametri + params_class = MyToolParams + + async def execute(self, tool_context: ToolContext, params: MyToolParams) -> ToolResult: + """Eseguire logica strumento""" + try: + # Implementare logica strumento + result_content = f"Elaborazione parametri: {params.param1}, {params.param2}, {params.param3}" + + # Restituire risultato + return ToolResult(content=result_content) + except Exception as e: + # Gestione errori + return ToolResult(error=f"Esecuzione strumento fallita: {e}") +``` + +Suggerimenti per la definizione della classe strumento: +- Fornire docstring dettagliata, specialmente la prima riga +- Specificare chiaramente l'attributo `params_class` +- Implementare la logica strumento nel metodo `execute` +- Utilizzare blocchi try-except per catturare possibili errori +- Restituire oggetto `ToolResult` formattato + +### 3.3 Flusso di Esecuzione degli Strumenti + +Il flusso completo di esecuzione degli strumenti è il seguente: + +1. Quando l'applicazione si avvia, `tool_factory` scannerà e registrerà automaticamente tutte le classi di strumenti con decoratore `@tool()` +2. Il chiamante crea oggetto `ToolContext`, contenente nome strumento e informazioni chiamata +3. Il chiamante esegue lo strumento attraverso `tool_executor.execute_tool_call()` +4. L'esecutore ottiene l'istanza strumento attraverso la factory degli strumenti +5. L'esecutore converte i parametri nel modello di parametri dello strumento +6. L'esecutore chiama il metodo `__call__` dell'istanza strumento +7. Il metodo `__call__` valida i parametri e chiama il metodo `execute` +8. Il metodo `execute` esegue la logica strumento e restituisce `ToolResult` +9. L'esecutore gestisce possibili errori e restituisce il risultato + +## 4. Migliori Pratiche + +### 4.1 Denominazione degli Strumenti + +- I nomi delle classi strumento utilizzano CamelCase, come `ListDir` +- I nomi strumento vengono convertiti automaticamente in snake_case, come `list_dir` +- Il nome file dovrebbe essere consistente con il nome strumento, come `list_dir.py` +- La descrizione dello strumento dovrebbe essere concisa e chiara, specialmente la prima riga + +### 4.2 Design dei Parametri + +- Utilizzare nomi parametri chiari, evitare abbreviazioni +- Utilizzare Field di Pydantic per aggiungere descrizioni dettagliate a ogni parametro +- Fornire valori predefiniti ragionevoli per parametri opzionali +- Utilizzare annotazioni di tipo precise +- Fornire suggerimenti user-friendly attraverso `get_custom_error_message` + +### 4.3 Implementazione degli Strumenti + +- Implementare strumenti focalizzati, seguire il principio di singola responsabilità +- Utilizzare blocchi try-except per gestire possibili errori +- Utilizzare annotazioni di tipo nel metodo execute +- Estrarre logica comune nella classe base o metodi ausiliari +- Restituire risultati formattati, evitare strutture annidate complesse + +### 4.4 Gestione degli Errori + +- Catturare e gestire possibili eccezioni +- Fornire messaggi di errore dettagliati, inclusi tipo errore e contesto +- Utilizzare meccanismo di messaggi di errore personalizzati per fornire suggerimenti user-friendly +- Registrare log di errore dettagliati, inclusi stack trace +- Restituire codici di errore e descrizioni significative + +### 4.5 Ottimizzazione delle Prestazioni + +- Evitare calcoli e operazioni I/O non necessarie +- Utilizzare I/O asincroni per migliorare le prestazioni concorrenti +- Memorizzare nella cache dati e risultati utilizzati frequentemente +- Limitare l'ambito di operazioni che richiedono molte risorse +- Fornire meccanismi di timeout per operazioni di lunga durata + +## 5. Problemi Comuni + +### 5.1 Strumento non Scoperto + +**Problema**: È stato aggiunto un nuovo strumento, ma il sistema non lo ha scoperto. + +**Soluzione**: +1. Assicurarsi che la classe strumento utilizzi il decoratore `@tool()` +2. Assicurarsi che il file strumento sia nella directory `app/tools` o sue sottodirectory +3. Assicurarsi che il nome della classe strumento e il nome file corrispondano +4. Riavviare l'applicazione o chiamare manualmente `tool_factory.initialize()` + +### 5.2 Validazione Parametri Fallita + +**Problema**: Durante l'esecuzione dello strumento viene riportato errore di validazione parametri. + +**Soluzione**: +1. Verificare che i parametri passati siano conformi alla definizione del modello parametri +2. Verificare che tutti i parametri obbligatori siano stati forniti +3. Verificare che i tipi dei parametri siano corretti +4. Implementare `get_custom_error_message` per fornire suggerimenti di errore user-friendly + +### 5.3 Esecuzione Strumento Fallita + +**Problema**: L'esecuzione dello strumento riporta errore. + +**Soluzione**: +1. Controllare le informazioni di errore dettagliate e lo stack trace nei log +2. Verificare la gestione degli errori nella logica dello strumento +3. Assicurarsi che tutti i servizi e risorse dipendenti siano disponibili +4. Verificare la funzionalità dello strumento attraverso test unitari in ambiente di sviluppo + +### 5.4 Problemi di Prestazioni + +**Problema**: L'esecuzione dello strumento è lenta o occupa molte risorse. + +**Soluzione**: +1. Utilizzare strumenti di analisi delle prestazioni per identificare i colli di bottiglia +2. Ottimizzare operazioni I/O, utilizzare elaborazione asincrona o batch +3. Memorizzare nella cache dati utilizzati frequentemente +4. Limitare l'ambito di operazioni che richiedono molte risorse +5. Considerare l'elaborazione batch per scenari con grandi quantità di dati + +--- + +# Original Chinese Content / Contenuto Originale Cinese + # 工具系统架构指南 本文档提供了 SuperMagic 工具系统架构的详细说明，包括设计原则、核心组件、工具开发方法和最佳实践。 diff --git a/backend/task-scheduler/README.md b/backend/task-scheduler/README.md index a989fba31..af4a5059a 100644 --- a/backend/task-scheduler/README.md +++ b/backend/task-scheduler/README.md @@ -1,5 +1,129 @@ # dtyq/task-scheduler +## 📦 Installazione +``` +composer require dtyq/task-scheduler +php bin/hyperf.php vendor:publish dtyq/task-scheduler +``` + +## 🚀 Utilizzo +Vedere il servizio: +``` +\Dtyq\TaskScheduler\Service\TaskSchedulerDomainService +``` + +## 📋 Spiegazione +> ⚠️ Supporta solo chiamate a livello di minuti + +### Metodi di schedulazione +1. ⏰ Schedulazione programmata +2. 🎯 Schedulazione specifica + +### Creazione di task schedulati +1. La schedulazione programmata richiede un timer per generare i dati dei task da eseguire nelle prossime n ore +2. Generare task di schedulazione basati sul tempo del task + +### Esecuzione dei task +1. Eseguire i task scaduti, cambiare lo stato, se ci sono errori eseguire l'evento di errore +2. Dopo la fine della schedulazione, registrare nella tabella di archivio + +### Esecuzione in background +1. Ogni giorno controllare i task di schedulazione completati oltre n giorni, eliminarli. Prevenire che la tabella di schedulazione diventi troppo grande +2. Ogni minuto controllare i task da eseguire nei prossimi n giorni, generare task di schedulazione +3. Ogni minuto controllare i task scaduti, eseguire + +### Database +1. Tabella di schedulazione task (task_scheduler) utilizzata per i record dei task specifici da eseguire +2. Tabella di archivio task (task_scheduler_log) utilizzata per salvare i record dei task completati, solo per archivio, per facilitare la visualizzazione della cronologia futura +3. Tabella dei task programmati (task_scheduler_crontab) utilizzata per salvare le regole dei task programmati + +## 🛠️ Ricordati di creare la struttura delle tabelle +```shell +php bin/hyperf.php migrate +``` + +```sql +-- auto-generated definition +create table task_scheduler +( + id bigint unsigned not null primary key, + external_id varchar(64) not null comment 'ID business', + name varchar(64) not null comment 'Nome', + expect_time datetime not null comment 'Tempo di esecuzione previsto', + actual_time datetime null comment 'Tempo di esecuzione effettivo', + type tinyint default 2 not null comment 'Tipo di schedulazione: 1 schedulazione programmata, 2 schedulazione specifica', + cost_time int default 0 not null comment 'Tempo impiegato millisecondi', + retry_times int default 0 not null comment 'Tentativi rimanenti', + status tinyint default 0 not null comment 'Stato', + callback_method json not null comment 'Metodo di callback', + callback_params json not null comment 'Parametri di callback', + remark varchar(255) default '' not null comment 'Nota', + creator varchar(64) default '' not null comment 'Creatore', + created_at datetime not null comment 'Tempo di creazione' +) + collate = utf8mb4_unicode_ci; + +create index task_scheduler_external_id_index + on task_scheduler (external_id); + +create index task_scheduler_status_expect_time_index + on task_scheduler (status, expect_time); + +-- auto-generated definition +create table task_scheduler_crontab +( + id bigint unsigned not null primary key, + name varchar(64) not null comment 'Nome', + crontab varchar(64) not null comment 'Espressione crontab', + last_gen_time datetime null comment 'Ultimo tempo di generazione', + enabled tinyint(1) default 1 not null comment 'Se abilitato', + retry_times int default 0 not null comment 'Totale tentativi', + callback_method json not null comment 'Metodo di callback', + callback_params json not null comment 'Parametri di callback', + remark varchar(255) default '' not null comment 'Nota', + creator varchar(64) default '' not null comment 'Creatore', + created_at datetime not null comment 'Tempo di creazione' +) + collate = utf8mb4_unicode_ci; + + + +-- auto-generated definition +-- auto-generated definition +create table task_scheduler_log +( + id bigint unsigned not null primary key, + task_id bigint unsigned not null comment 'ID task', + external_id varchar(64) not null comment 'Identificatore business', + name varchar(64) not null comment 'Nome', + expect_time datetime not null comment 'Tempo di esecuzione previsto', + actual_time datetime null comment 'Tempo di esecuzione effettivo', + type tinyint default 2 not null comment 'Tipo', + cost_time int default 0 not null comment 'Tempo impiegato', + status tinyint default 0 not null comment 'Stato', + callback_method json not null comment 'Metodo di callback', + callback_params json not null comment 'Parametri di callback', + remark varchar(255) default '' not null comment 'Nota', + creator varchar(64) default '' not null comment 'Creatore', + created_at datetime not null comment 'Tempo di creazione', + result json null comment 'Risultato' +) + collate = utf8mb4_unicode_ci; + +create index task_scheduler_log_external_id_index + on task_scheduler_log (external_id); + +create index task_scheduler_log_status_expect_time_index + on task_scheduler_log (status, expect_time); + +create index task_scheduler_log_task_id_index + on task_scheduler_log (task_id); +``` + +--- + +# dtyq/task-scheduler + ## 安装 ``` composer require dtyq/task-scheduler diff --git a/backend/tiptap/.github/CONTRIBUTING.md b/backend/tiptap/.github/CONTRIBUTING.md index b4ae1c4a7..4686ce0cf 100644 --- a/backend/tiptap/.github/CONTRIBUTING.md +++ b/backend/tiptap/.github/CONTRIBUTING.md @@ -1,3 +1,55 @@ +# Contributi + +I contributi sono **benvenuti** e saranno completamente **riconosciuti**. + +Si prega di leggere e comprendere la guida ai contributi prima di creare un issue o una pull request. + +## Etichetta + +Questo progetto è open source, e come tale, i maintainer dedicano il loro tempo libero a costruire e mantenere il codice sorgente contenuto al suo interno. Rendono il codice liberamente disponibile nella speranza che sia utile ad altri sviluppatori. Sarebbe estremamente ingiusto che subissero abusi o rabbia per il loro duro lavoro. + +Si prega di essere rispettosi nei confronti dei maintainer quando si sollevano issue o si presentano pull request. Mostriamo al mondo che gli sviluppatori sono persone civili e altruiste. + +È dovere del maintainer garantire che tutti i contributi al progetto siano di qualità sufficiente per beneficiare il progetto. Molti sviluppatori hanno competenze, punti di forza e debolezze diversi. Rispettate la decisione del maintainer e non siate arrabbiati o offensivi se il vostro contributo non viene utilizzato. + +## Viabilità + +Quando si richiedono o si propongono nuove funzionalità, considerare prima se potrebbero essere utili ad altri. I progetti open source sono utilizzati da molti sviluppatori, che potrebbero avere esigenze completamente diverse dalle proprie. Pensate se la vostra funzionalità è probabile che venga utilizzata da altri utenti del progetto. + +## Procedura + +Prima di segnalare un issue: + +- Tentare di replicare il problema, per assicurarsi che non sia stato un incidente occasionale. +- Verificare che il suggerimento di funzionalità non sia già presente nel progetto. +- Controllare la scheda delle pull request per assicurarsi che il bug non abbia già una correzione in corso. +- Controllare la scheda delle pull request per assicurarsi che la funzionalità non sia già in corso. + +Prima di inviare una pull request: + +- Controllare il codebase per assicurarsi che la funzionalità non esista già. +- Controllare le pull request per assicurarsi che nessun altro abbia già inviato la funzionalità o la correzione. + +## Requisiti + +Se il maintainer del progetto ha requisiti aggiuntivi, li troverete elencati qui. + +- **[PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)** - Il modo più semplice per applicare le convenzioni è installare [PHP Code Sniffer](https://pear.php.net/package/PHP_CodeSniffer). + +- **Aggiungere test!** - La vostra patch non sarà accettata se non ha test. + +- **Documentare qualsiasi cambiamento nel comportamento** - Assicurarsi che il `README.md` e qualsiasi altra documentazione rilevante siano mantenuti aggiornati. + +- **Considerare il nostro ciclo di rilascio** - Cerchiamo di seguire [SemVer v2.0.0](https://semver.org/). Rompere casualmente le API pubbliche non è un'opzione. + +- **Una pull request per funzionalità** - Se si vuole fare più di una cosa, inviare più pull request. + +- **Inviare una cronologia coerente** - Assicurarsi che ogni singolo commit nella pull request sia significativo. Se si sono dovuti fare più commit intermedi durante lo sviluppo, si prega di [schiacciarli](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) prima di inviare. + +**Buon coding**! + +--- + # Contributing Contributions are **welcome** and will be fully **credited**. diff --git a/backend/tiptap/.github/SECURITY.md b/backend/tiptap/.github/SECURITY.md index 49812f699..0482cd9ef 100644 --- a/backend/tiptap/.github/SECURITY.md +++ b/backend/tiptap/.github/SECURITY.md @@ -1,3 +1,9 @@ +# Politica di Sicurezza + +Se scoprite problemi relativi alla sicurezza, si prega di inviare un'email a humans@tiptap.dev invece di utilizzare il tracker delle issue. + +--- + # Security Policy If you discover any security related issues, please email humans@tiptap.dev instead of using the issue tracker. diff --git a/docs/en/development/advanced/init.md b/docs/en/development/advanced/init.md index 1b0a861b8..3b4a224da 100644 --- a/docs/en/development/advanced/init.md +++ b/docs/en/development/advanced/init.md @@ -1,3 +1,63 @@ +# 🚀 Guida all'Inizializzazione del Sistema Magic Service + +Questo documento descrive brevemente i passaggi di inizializzazione per il sistema Magic Service, inclusa la popolazione di dati account e utente, la configurazione dell'ambiente e l'implementazione della funzionalità di verifica del login. + +## 1. 👥 Inizializzazione Dati Account e Utente + +Il sistema utilizza il seeder di dati `seeders/initial_account_and_user_seeder.php` per inizializzare i dati account e utente, principalmente per compiere le seguenti attività: + +- Creare almeno 2 record di account umani nella tabella `magic_contact_accounts` +- Creare dati utente per ciascun account sotto 2 diverse organizzazioni +- Utilizzare `App\Infrastructure\Util\IdGenerator` per generare automaticamente magic_id +- Implementare il controllo di dati duplicati per evitare creazioni duplicate + +## 2. ⚙️ Inizializzazione Configurazione Ambiente + +Il sistema utilizza il seeder di dati `seeders/initial_environment_seeder.php` per inizializzare i dati di configurazione dell'ambiente, principalmente per compiere le seguenti attività: + +- Scrivere la configurazione dell'ambiente di produzione, inclusi tipo di deployment, tipo di ambiente, configurazione privata, ecc. +- Scrivere la configurazione dell'ambiente di test per scopi di sviluppo e test + +> **Importante:** L'ID dell'ambiente di produzione del sistema è 10000. Assicurati che `MAGIC_ENV_ID` sia impostato su `10000` nelle variabili d'ambiente. + +## 4. 🔄 Passaggi di Esecuzione e Test + +### 4.1 Esegui Seeding Dati + +Esegui i seguenti comandi per popolare i dati account e ambiente: + +```bash +php bin/hyperf.php db:seed --path=seeders/initial_account_and_user_seeder.php +php bin/hyperf.php db:seed --path=seeders/initial_environment_seeder.php +``` + +### 4.2 Riavvia Servizio + +Carica la nuova configurazione delle route: + +```bash +php bin/hyperf.php server:restart +``` + +### 4.3 Testa Funzionalità Login + +Utilizza il seguente comando per testare l'interfaccia di login: + +```bash +curl -X POST -H "Content-Type: application/json" -d '{"email":"admin@example.com","password":"138001","organization_code":""}' http://localhost:9501/api/v1/login/check +``` + +## 5. 🔐 Informazioni Password + +Account predefiniti e password: + +- Account `13812345678`: Password è `letsmagic.ai` +- Account `13912345678`: Password è `letsmagic.ai` + +Negli ambienti di produzione, assicurati l'implementazione di meccanismi sicuri di archiviazione e verifica delle password. + +--- + # Magic Service System Initialization Guide This document briefly describes the initialization steps for the Magic Service system, including account and user data population, environment configuration, and login verification functionality implementation. @@ -54,4 +114,4 @@ Default Accounts and password: - Account `13812345678`: Password is `letsmagic.ai` - Account `13912345678`: Password is `letsmagic.ai` -In production environments, please ensure the implementation of secure password storage and verification mechanisms. \ No newline at end of file +In production environments, please ensure the implementation of secure password storage and verification mechanisms. \ No newline at end of file diff --git a/docs/en/development/advanced/permission.md b/docs/en/development/advanced/permission.md index 2220187f6..a2c12b800 100644 --- a/docs/en/development/advanced/permission.md +++ b/docs/en/development/advanced/permission.md @@ -1,3 +1,15 @@ +# 🔐 Sistema di Gestione Permessi + +Questo documento descrive come utilizzare il sistema di gestione permessi, che permette di concedere permessi specifici a utenti con numeri di cellulare specifici. + +## Concetti Base + +Il sistema di gestione permessi fornisce un modo semplice ma efficiente per controllare l'accesso a funzioni e interfacce specifiche. Il sistema include i seguenti concetti chiave: + +1. **Amministratore Globale**: Utenti con accesso a tutte le funzioni +2. **Mappatura Permessi**: Mappatura di permessi specifici a liste di numeri di cellulare consentiti +3. **Modalità Rigorosa**: Un'opzione di configurazione che, quando abilitata, permette l'accesso solo a permessi configurati esplicitamente + # Permission Management System This document describes how to use the permission management system, which allows granting specific permissions to specific mobile number users. @@ -10,6 +22,48 @@ The permission management system provides a simple yet efficient way to control 2. **Permission Mapping**: Mapping of specific permissions to lists of allowed mobile numbers 3. **Strict Mode**: A configuration option that, when enabled, only allows access to explicitly configured permissions +## 🔑 Enumerazione Tipi di Permesso + +Il sistema definisce la seguente enumerazione dei tipi di permesso (`SuperPermissionEnum`): + +```php +enum SuperPermissionEnum: string +{ + // Global Administrator + case GLOBAL_ADMIN = 'global_admin'; + + // Flow Administrator + case FLOW_ADMIN = 'flow_admin'; + + // Assistant Administrator + case ASSISTANT_ADMIN = 'assistant_admin'; + + // Large Model Configuration Management + case MODEL_CONFIG_ADMIN = 'model_config_admin'; + + // Hide Department or User + case HIDE_USER_OR_DEPT = 'hide_user_or_dept'; + + // Privileged Message Sending + case PRIVILEGE_SEND_MESSAGE = 'privilege_send_message'; + + // Magic Environment Management + case MAGIC_ENV_MANAGEMENT = 'magic_env_management'; + + // Service Provider Administrator + case SERVICE_PROVIDER_ADMIN = 'service_provider_admin'; + + // Super Magic Invite Use User + case SUPER_INVITE_USER = 'super_magic_invite_use_user'; + + // Super Magic Board Administrator + case SUPER_MAGIC_BOARD_ADMIN = 'super_magic_board_manager'; + + // Super Magic Board Operator + case SUPER_MAGIC_ BOARD_OPERATOR = 'super_magic_board_operator'; +} +``` + ## Permission Type Enumeration The system defines the following permission type enumeration (`SuperPermissionEnum`): @@ -52,6 +106,19 @@ enum SuperPermissionEnum: string } ``` +### 📋 Descrizioni Tipi di Permesso + +| Enum Permesso | Valore Permesso | Descrizione | +|---------|-------|------| +| GLOBAL_ADMIN | 'global_admin' | Permesso amministratore globale, ha la massima autorità di sistema, può accedere a tutte le funzioni | +| FLOW_ADMIN | 'flow_admin' | Permesso amministratore flusso, può gestire e configurare flussi nel sistema | +| ASSISTANT_ADMIN | 'assistant_admin' | Permesso amministratore assistente, può gestire funzioni assistente nel sistema | +| MODEL_CONFIG_ADMIN | 'model_config_admin' | Permesso configurazione modello grande, può configurare e gestire impostazioni relative a modelli di linguaggio grandi | +| HIDE_USER_OR_DEPT | 'hide_user_or_dept' | Permesso nascondi utente o dipartimento, può nascondere utenti o dipartimenti specifici nel sistema | +| PRIVILEGE_SEND_MESSAGE | 'privilege_send_message' | Permesso invio messaggio privilegiato, può inviare tipi speciali di messaggi | +| MAGIC_ENV_MANAGEMENT | 'magic_env_management' | Permesso gestione ambiente magico, può gestire configurazione multi-ambiente | +| SERVICE_PROVIDER_ADMIN | 'service_provider_admin' | Permesso amministratore fornitore servizio, può gestire configurazione e funzioni relative al fornitore servizio | + ### Permission Type Descriptions | Permission Enum | Permission Value | Description | @@ -65,6 +132,31 @@ enum SuperPermissionEnum: string | MAGIC_ENV_MANAGEMENT | 'magic_env_management' | Magic environment management permission, can manage multi-environment configuration | | SERVICE_PROVIDER_ADMIN | 'service_provider_admin' | Service provider administrator permission, can manage service provider related configuration and functions | +## ⚙️ File di Configurazione + +Il sistema di permessi è principalmente gestito attraverso un file di configurazione situato in: `config/autoload/permission.php` + +### Descrizione Elementi Configurazione + +```php + ['mobile1', 'mobile2', ...] + 'permissions' => Json::decode(env('PERMISSIONS', '[]')), +]; +``` + +### Configurazione Variabile Ambiente + +Il sistema supporta configurazione attraverso variabili ambiente, migliorando la flessibilità di deployment: + +``` +# Permission system configuration +PERMISSIONS={"flow_admin":["13800000000","13900000000"]} +``` + ## Configuration File The permission system is primarily managed through a configuration file located at: `config/autoload/permission.php` @@ -90,6 +182,13 @@ The system supports configuration through environment variables, improving deplo PERMISSIONS={"flow_admin":["13800000000","13900000000"]} ``` +## 📏 Regole Abbinamento Permessi + +L'abbinamento permessi segue queste regole: + +1. Prima controlla se l'utente è un amministratore globale, se sì, permette accesso a tutti i permessi +2. Se non è amministratore globale, controlla se l'utente ha il permesso specifico richiesto + ## Permission Matching Rules Permission matching follows these rules: @@ -97,6 +196,56 @@ Permission matching follows these rules: 1. First check if the user is a global administrator, if yes, allow access to all permissions 2. If not a global administrator, check if the user has the requested specific permission +## 💻 Utilizzo nel Codice +### Verifica Permesso Manuale + +In alcuni casi speciali, potresti aver bisogno di controllare permessi manualmente nel codice: + +```php +use App\Infrastructure\Util\Auth\PermissionChecker; +use App\Infrastructure\Core\Exception\ExceptionBuilder; +use App\ErrorCode\GenericErrorCode; +use App\Application\Kernel\SuperPermissionEnum; + +class YourClass +{ + public function __construct( + private readonly PermissionChecker $permissionChecker, + ) { + } + + public function yourMethod(RequestInterface $request) + { + $authorization = $this->getAuthorization(); + $mobile = $authorization->getMobile(); + + if (!PermissionChecker::mobileHasPermission($mobile, SuperPermissionEnum::FLOW_ADMIN)) { + ExceptionBuilder::throw(GenericErrorCode::AccessDenied); + } + + // Execute subsequent business logic... + } +} +``` + +### Utilizzo Tipi Enumerazione Permessi + +Il sistema fornisce il tipo enumerazione permessi `PermissionEnum` per definire e controllare vari permessi: + +```php +use App\Application\Kernel\SuperPermissionEnum; +use App\Infrastructure\Util\Auth\PermissionChecker; + +// Check if user has global administrator permission +$hasGlobalAdmin = PermissionChecker::mobileHasPermission($mobile, SuperPermissionEnum::GLOBAL_ADMIN); + +// Check if user has flow administrator permission +$hasFlowAdmin = PermissionChecker::mobileHasPermission($mobile, SuperPermissionEnum::FLOW_ADMIN); + +// Check if user has assistant administrator permission +$hasAssistantAdmin = PermissionChecker::mobileHasPermission($mobile, SuperPermissionEnum::ASSISTANT_ADMIN); +``` + ## Using in Code ### Manual Permission Verification @@ -147,6 +296,21 @@ $hasFlowAdmin = PermissionChecker::mobileHasPermission($mobile, SuperPermissionE $hasAssistantAdmin = PermissionChecker::mobileHasPermission($mobile, SuperPermissionEnum::ASSISTANT_ADMIN); ``` +## 🧪 Test + +Il sistema fornisce test unitari, che puoi eseguire con il seguente comando: + +```bash +vendor/bin/phpunit test/Cases/Infrastructure/Util/Auth/PermissionCheckerTest.php +``` + +I test coprono i seguenti aspetti: + +1. Controllo Permesso Amministratore Globale - Verifica che amministratori globali possano accedere a tutti i permessi +2. Controllo Permesso Specifico - Verifica controllo accesso utente per permessi specifici +3. Scenario Senza Permesso - Verifica che utenti non autorizzati siano correttamente negati +4. Vari Casi Limite - Gestisce casi eccezionali come numeri cellulare vuoti + ## Testing The system provides unit tests, which you can run with the following command: @@ -162,6 +326,15 @@ Tests cover the following aspects: 3. No Permission Scenario - Verify unauthorized users are correctly denied 4. Various Edge Cases - Handle exceptional cases such as empty mobile numbers +## 💡 Raccomandazioni Utilizzo + +1. Configura permessi appropriati per diversi livelli di funzionalità per garantire sicurezza di caratteristiche critiche +2. Configura amministratori globali appropriati per ambienti di sviluppo e test per facilitare sviluppo e test +3. Considera abilitare modalità rigorosa in ambienti di produzione per migliorare sicurezza +4. Audita regolarmente configurazioni permessi e rimuovi permessi non necessari +5. Usa variabili ambiente per configurare permessi per aggiustamento flessibile attraverso ambienti diversi +6. Evita aggiungere troppi utenti a liste permessi per mantenere semplicità ed efficienza nella gestione permessi + ## Usage Recommendations 1. Configure appropriate permissions for different levels of functionality to ensure security of critical features @@ -171,6 +344,21 @@ Tests cover the following aspects: 5. Use environment variables to configure permissions for flexible adjustment across different environments 6. Avoid adding too many users to permission lists to maintain simplicity and efficiency in permission management +# 📄 Valore Variabile Ambiente PERMISSIONS + +```json +{ + "global_admin": ["13800000001", "13800000002"], + "flow_admin": ["13800000003", "13800000004", "13800000005"], + "assistant_admin": ["13800000006", "13800000007"], + "model_config_admin": ["13800000008", "13800000009"], + "hide_user_or_dept": ["13800000010", "13800000011"], + "privilege_send_message": ["13800000012", "13800000013"], + "magic_env_management": ["13800000014", "13800000015"], + "service_provider_admin": ["13800000016", "13800000017"] +} +``` + # PERMISSIONS Environment Variable Value ```json diff --git a/docs/en/development/deploy/docker.md b/docs/en/development/deploy/docker.md index ada04931d..a81b4dba5 100644 --- a/docs/en/development/deploy/docker.md +++ b/docs/en/development/deploy/docker.md @@ -1,27 +1,50 @@ -## Quick Start +## Quick Start 🚀 Supports Mac OS and Linux operating systems. Windows systems can run through docker-compose. -### 1. Clone the Project +### Avvio Rapido 🚀 +Supporta i sistemi operativi Mac OS e Linux. I sistemi Windows possono essere eseguiti tramite docker-compose. + +### 1. Clone the Project 📥 ```bash git clone https://github.com/dtyq/magic.git cd magic ``` -### 2. Configure Environment Variables +### 1. Clona il Progetto 📥 +```bash +git clone https://github.com/dtyq/magic.git +cd magic +``` + +### 2. Configure Environment Variables ⚙️ Configure Magic environment variables. You must configure at least one large language model environment variable for proper functionality. Copy the `.env.example` file to `.env` and modify the configuration as needed: ```bash cp .env.example .env ``` -### 3. Start the Service +### 2. Configura le Variabili d'Ambiente ⚙️ +Configura le variabili d'ambiente di Magic. Devi configurare almeno una variabile d'ambiente per il modello di linguaggio di grandi dimensioni per il corretto funzionamento. +Copia il file `.env.example` in `.env` e modifica la configurazione come necessario: +```bash +cp .env.example .env +``` + +### 3. Start the Service ▶️ ```bash # Start the service in foreground ./bin/magic.sh start ``` -### 4. Other Commands +### 3. Avvia il Servizio ▶️ + +```bash +# Avvia il servizio in primo piano +./bin/magic.sh start +``` + +### 4. Other Commands 🛠️ ```bash # Display help information @@ -46,7 +69,32 @@ cp .env.example .env ./bin/magic.sh logs ``` -### 4. Access Services +### 4. Altri Comandi 🛠️ + +```bash +# Visualizza le informazioni di aiuto +./bin/magic.sh help + +# Avvia il servizio in primo piano +./bin/magic.sh start + +# Avvia il servizio in background +./bin/magic.sh daemon + +# Ferma il servizio +./bin/magic.sh stop + +# Riavvia il servizio +./bin/magic.sh restart + +# Controlla lo stato del servizio +./bin/magic.sh status + +# Visualizza i log del servizio +./bin/magic.sh logs +``` + +### 4. Access Services 🌐 - API Service: http://localhost:9501 - Web Application: http://localhost:8080 - Account `13812345678`：Password `letsmagic.ai` @@ -54,3 +102,12 @@ cp .env.example .env - RabbitMQ Management Interface: http://localhost:15672 - Username: admin - Password: magic123456 + +### 4. Accedi ai Servizi 🌐 +- Servizio API: http://localhost:9501 +- Applicazione Web: http://localhost:8080 + - Account `13812345678`：Password `letsmagic.ai` + - Account `13912345678`：Password `letsmagic.ai` +- Interfaccia di Gestione RabbitMQ: http://localhost:15672 + - Nome utente: admin + - Password: magic123456 diff --git a/docs/en/development/deploy/environment.md b/docs/en/development/deploy/environment.md index 92dc1ae33..1b9cc8e7e 100644 --- a/docs/en/development/deploy/environment.md +++ b/docs/en/development/deploy/environment.md @@ -1,3 +1,350 @@ +# Guida alla Configurazione delle Variabili d'Ambiente 🛠️ + +Questo documento fornisce informazioni dettagliate sulle variabili d'ambiente utilizzate nel progetto Magic, servendo come riferimento per lo sviluppo e il deployment. + +## Panoramica 📋 + +Il progetto Magic utilizza il file `.env` per gestire le configurazioni delle variabili d'ambiente. Durante il deployment o lo sviluppo del progetto, è necessario configurare correttamente queste variabili d'ambiente per garantire il normale funzionamento del sistema. + +## File di Configurazione 📄 + +Il sistema fornisce un file `.env.example` predefinito. Puoi copiare e creare la tua configurazione utilizzando il seguente comando: + +```bash +cp .env.example .env +``` + +Quindi modifica gli elementi di configurazione nel file `.env` in base alle tue esigenze effettive. + +## Categorie di Configurazione 🏷️ + +Le variabili d'ambiente possono essere classificate nelle seguenti categorie: + +### 1. Configurazione di Servizio Base ⚙️ + +#### Tag di Versione + +``` +# Tag di versione del servizio +MAGIC_SERVICE_TAG=latest +MAGIC_WEB_TAG=latest + +# Tipo di versione (ENTERPRISE | COMMUNITY) +MAGIC_EDITION=COMMUNITY +``` + +#### Configurazione Repository Git + +``` +# URL del Repository Git (Predefinito utilizzando GitHub) +GIT_REPO_URL=git@github.com:dtyq +``` + +### 2. Configurazione Database 🗄️ + +#### Configurazione MySQL + +``` +# Configurazione MySQL +MYSQL_USER=magic +MYSQL_PASSWORD=magic123456 +MYSQL_DATABASE=magic +MYSQL_DATA=/var/lib/mysql +MYSQL_MAX_CONNECTIONS=1000 +MYSQL_SHARED_BUFFERS=128MB +MYSQL_WORK_MEM=4MB +MYSQL_MAINTENANCE_WORK_MEM=64MB +MYSQL_EFFECTIVE_CACHE_SIZE=4096MB + +# Configurazione connessione MySQL dell'applicazione +DB_DRIVER=mysql +DB_HOST=db +DB_PORT=3306 +DB_USERNAME=magic +DB_PASSWORD=magic123456 +DB_DATABASE=magic +DB_CHARSET=utf8mb4 +DB_COLLATION=utf8mb4_unicode_ci +DB_PREFIX= +``` + +#### Configurazione Redis + +``` +# Configurazione Redis +REDIS_HOST=redis +REDIS_AUTH=magic123456 +REDIS_PORT=6379 +REDIS_DB=0 +REDIS_PASSWORD=magic123456 +``` + +#### Configurazione RabbitMQ + +``` +# Configurazione RabbitMQ +AMQP_HOST=rabbitmq +AMQP_PORT=5672 +AMQP_USER=admin +AMQP_PASSWORD=magic123456 +AMQP_VHOST=magic-chat +``` + +#### Configurazione OpenSearch + +``` +# Configurazione OpenSearch +OPENSEARCH_DISCOVERY_TYPE=single-node +OPENSEARCH_BOOTSTRAP_MEMORY_LOCK=true +OPENSEARCH_JAVA_OPTS_MIN=512m +OPENSEARCH_JAVA_OPTS_MAX=1024m +OPENSEARCH_INITIAL_ADMIN_PASSWORD=Qazwsxedc!@#123 +OPENSEARCH_MEMLOCK_SOFT=-1 +OPENSEARCH_MEMLOCK_HARD=-1 +OPENSEARCH_NOFILE_SOFT=65536 +OPENSEARCH_NOFILE_HARD=65536 +``` + +#### Configurazione Qdrant + +``` +# Configurazione Qdrant +QDRANT_API_KEY=magic123456 +ODIN_QDRANT_BASE_URI=http://qdrant +ODIN_QDRANT_API_KEY= +``` + +### 3. Configurazione Applicazione 📱 + +#### Configurazione Base dell'Applicazione + +``` +APP_NAME=magic_service +APP_ENV=dev +APP_HOST= + +MAGIC_API_DEFAULT_ACCESS_TOKEN= +MAGIC_PRIVILEGED_PASSWORD= + +# Configurazione permessi super admin +SUPER_WHITELISTS={"privilege_send_message":["13800000000","13900000000"]} +# Whitelist permessi backend gestione organizzazione +ORGANIZATION_WHITELISTS={} +``` + +#### Interruttori di Funzionalità 🔄 + +``` +# Abilita consumer +ENABLE_CONSUME=true +# Abilita messaggi chat +ENABLE_CHAT_MESSAGE=true +# Abilita sequenza chat +ENABLE_CHAT_SEQ=true +# Abilita Magic Watchdog (può essere disabilitato per sviluppo locale) +ENABLE_MAGIC_WATCHDOG=false + +# Interruttori comuni +AZURE_OPENAI_GPT4O_ENABLED=false +DOUBAO_PRO_32K_ENABLED=false +DEEPSEEK_R1_ENABLED=false +DEEPSEEK_V3_ENABLED=false +DOUBAO_EMBEDDING_ENABLED=false +MISC_DMETA_EMBEDDING_ENABLED=false +``` + +### 4. Configurazione Modello AI 🤖 + +#### Configurazione Azure OpenAI + +``` +# Azure OpenAI GPT-4 +AZURE_OPENAI_4_API_KEY= +AZURE_OPENAI_4_API_BASE= +AZURE_OPENAI_4_API_VERSION=2023-08-01-preview +AZURE_OPENAI_4_DEPLOYMENT_NAME= + +# Azure OpenAI GPT-3.5 Turbo +AZURE_OPENAI_35_TURBO_API_KEY= +AZURE_OPENAI_35_TURBO_API_BASE= +AZURE_OPENAI_35_TURBO_API_VERSION=2023-08-01-preview +AZURE_OPENAI_35_TURBO_DEPLOYMENT_NAME= + +# AzureOpenAI GPT-4o +AZURE_OPENAI_4O_GLOBAL_MODEL=gpt-4o-global +AZURE_OPENAI_4O_GLOBAL_API_KEY= +AZURE_OPENAI_4O_GLOBAL_BASE_URL= +AZURE_OPENAI_4O_GLOBAL_API_VERSION=2024-10-21 +AZURE_OPENAI_4O_GLOBAL_DEPLOYMENT_NAME=gpt-4o-global +``` + +#### Configurazione Modello Doubao + +``` +# Doubao Pro 32k +DOUBAO_PRO_32K_ENDPOINT=doubao-1.5-pro-32k +DOUBAO_PRO_32K_API_KEY= +DOUBAO_PRO_32K_BASE_URL=https://ark.cn-beijing.volces.com + +# Doubao Embedding +DOUBAO_EMBEDDING_ENDPOINT=doubao-embedding-text-240715 +DOUBAO_EMBEDDING_API_KEY= +DOUBAO_EMBEDDING_BASE_URL=https://ark.cn-beijing.volces.com +DOUBAO_EMBEDDING_VECTOR_SIZE=2048 +``` + +#### Configurazione Modello DeepSeek + +``` +# DeepSeek R1 +DEEPSEEK_R1_ENDPOINT=deepseek-reasoner +DEEPSEEK_R1_API_KEY= +DEEPSEEK_R1_BASE_URL=https://api.deepseek.com + +# DeepSeek V3 +DEEPSEEK_V3_ENDPOINT=deepseek-chat +DEEPSEEK_V3_API_KEY= +DEEPSEEK_V3_BASE_URL=https://api.deepseek.com +``` + +#### Altre Configurazioni Servizio AI + +``` +# dmeta-embedding +MISC_DMETA_EMBEDDING_ENDPOINT=dmeta-embedding +MISC_DMETA_EMBEDDING_API_KEY= +MISC_DMETA_EMBEDDING_BASE_URL= +MISC_DMETA_EMBEDDING_VECTOR_SIZE=768 + +# Conversione HD +MIRACLE_VISION_KEY= +MIRACLE_VISION_SECRET= +``` + +### 5. Configurazione Servizio Esterno 🌐 + +#### Configurazione Ricerca Google + +``` +# Proxy richiesto per ricerca Google +HTTP_PROXY= +GOOGLE_SEARCH_API_KEY= +# Quando si utilizza Google, specificare il cx di ricerca (GOOGLE_SEARCH_ENGINE_ID) +GOOGLE_SEARCH_CX= +BACKEND=GOOGLE +RELATED_QUESTIONS=true +``` + +#### Credenziali Applicazione + +``` +# Credenziali applicazione +APP_ID= +APP_SECRET= +APP_CODE= + +# Whitelist CODE +CODE_WHITE_ACCOUNT_ID= + +# ID ambiente magic predefinito +DEFAULT_MAGIC_ENVIRONMENT_ID= + +# ID ambiente magic +MAGIC_ENV_ID=1000 +``` + +### 6. Configurazione Archiviazione File 📁 + +#### Tipo Driver File + +``` +# Driver File +FILE_DRIVER=local # Opzioni disponibili: local, oss, tos +``` + +#### Configurazione Driver File Locale + +``` +# Configurazione Driver File Locale +FILE_LOCAL_ROOT= # Directory root archiviazione locale, es.: /app/storage/files +FILE_LOCAL_READ_HOST= # Dominio lettura file, es.: https://example.com +FILE_LOCAL_WRITE_HOST= # Dominio upload file, es.: https://upload.example.com +``` + +#### Configurazione Archiviazione Aliyun OSS + +``` +# Configurazione Driver File Aliyun OSS - Privato +FILE_PRIVATE_ALIYUN_ACCESS_ID= # Aliyun AccessKey ID +FILE_PRIVATE_ALIYUN_ACCESS_SECRET= # Aliyun AccessKey Secret +FILE_PRIVATE_ALIYUN_BUCKET= # Nome bucket OSS +FILE_PRIVATE_ALIYUN_ENDPOINT= # Dominio accesso OSS, es.: oss-cn-hangzhou.aliyuncs.com +FILE_PRIVATE_ALIYUN_ROLE_ARN= # Opzionale, per ruolo ARN autorizzazione temporanea STS + +# Configurazione Driver File Aliyun OSS - Pubblico +FILE_PUBLIC_ALIYUN_ACCESS_ID= # Aliyun AccessKey ID +FILE_PUBLIC_ALIYUN_ACCESS_SECRET= # Aliyun AccessKey Secret +FILE_PUBLIC_ALIYUN_BUCKET= # Nome bucket OSS +FILE_PUBLIC_ALIYUN_ENDPOINT= # Dominio accesso OSS +FILE_PUBLIC_ALIYUN_ROLE_ARN= # Opzionale, per ruolo ARN autorizzazione temporanea STS +``` + +#### Configurazione Archiviazione Volc Engine TOS + +``` +# Configurazione Driver File Volc Engine TOS - Privato +FILE_PRIVATE_TOS_REGION= # Regione TOS, es.: cn-beijing +FILE_PRIVATE_TOS_ENDPOINT= # Dominio accesso TOS +FILE_PRIVATE_TOS_AK= # Volc Engine AccessKey +FILE_PRIVATE_TOS_SK= # Volc Engine SecretKey +FILE_PRIVATE_TOS_BUCKET= # Nome bucket TOS +FILE_PRIVATE_TOS_TRN= # Opzionale, per ruolo ARN autorizzazione temporanea STS + +# Configurazione Driver File Volc Engine TOS - Pubblico +FILE_PUBLIC_TOS_REGION= # Regione TOS +FILE_PUBLIC_TOS_ENDPOINT= # Dominio accesso TOS +FILE_PUBLIC_TOS_AK= # Volc Engine AccessKey +FILE_PUBLIC_TOS_SK= # Volc Engine SecretKey +FILE_PUBLIC_TOS_BUCKET= # Nome bucket TOS +FILE_PUBLIC_TOS_TRN= # Opzionale, per ruolo ARN autorizzazione temporanea STS +``` + +### 7. Configurazione Applicazione Web 🌐 + +#### Configurazione Servizio Frontend + +``` +# Configurazione applicazione web +PORT=8080 +MAGIC_SOCKET_BASE_URL=ws://localhost:9502 +MAGIC_SERVICE_BASE_URL=http://localhost:9501 +``` + +## Raccomandazioni di Configurazione 💡 + +1. **Ambiente di Sviluppo**: Copia `.env.example` in `.env`, regola la configurazione in base al tuo ambiente locale +2. **Ambiente di Test**: Utilizza configurazioni simili alla produzione ma con meno risorse +3. **Ambiente di Produzione**: Assicurati che siano impostate password forti e utilizza configurazioni di servizio esterno più affidabili + +## Raccomandazioni di Sicurezza 🔒 + +1. Non committare il file `.env` nel repository del codice +2. Cambia regolarmente password e chiavi API +3. Utilizza il principio del privilegio minimo per configurare i permessi di accesso ai servizi esterni +4. Negli ambienti di produzione, utilizza sistemi di gestione password o metodi di iniezione di variabili d'ambiente invece di modificare direttamente il file `.env` + +## Note Speciali su Driver File 📝 + +Per configurazioni dettagliate del driver file e metodi di utilizzo, fai riferimento alla [Guida all'Uso del Driver File](./file-driver.md). + +## Note sul Primo Deployment 🚀 + +1. Durante il primo deployment, utilizzando il comando `./bin/magic.sh start` copierà automaticamente `.env.example` in `.env` +2. Se utilizzi servizi di archiviazione cloud, devi eseguire il comando di inizializzazione del file system: `php bin/hyperf.php file:init` +3. Dopo aver modificato le variabili d'ambiente, devi riavviare il servizio affinché le modifiche abbiano effetto + +--- + # Environment Variables Configuration Guide This document provides detailed information about the environment variables used in the Magic project, serving as a reference for development and deployment. diff --git a/docs/en/development/deploy/file-driver.md b/docs/en/development/deploy/file-driver.md index 14a988769..331c7ad2d 100644 --- a/docs/en/development/deploy/file-driver.md +++ b/docs/en/development/deploy/file-driver.md @@ -1,3 +1,261 @@ +# 📁 Guida all'Uso del File Driver + +Questo documento fornisce informazioni dettagliate sui driver di archiviazione file supportati nel progetto Magic Service, metodi di configurazione e scenari d'uso. + +## ☁️ Panoramica + +Magic Service supporta molteplici driver di archiviazione file che possono essere configurati in modo flessibile secondo diversi ambienti e requisiti. Attualmente, supporta i seguenti tre tipi di driver: + +1. File System Locale (Local) +2. Archiviazione Oggetto Cloud Alibaba (OSS) +3. Archiviazione Oggetto Cloud ByteDance (TOS) + +Tutti gli archivi file seguono due modalità di accesso: +- **Archiviazione Privata**: File che richiedono autorizzazione per l'accesso +- **Archiviazione Pubblica**: File che possono essere accessibili senza autorizzazione + +## ⚙️ Metodi di Configurazione + +### Configurazione Base + +Prima, imposta il tipo di driver file nel file `.env`: + +``` +# File Driver +FILE_DRIVER=local # Opzioni: local, oss, tos +``` + +### Driver File System Locale (local) + +Quando `FILE_DRIVER=local`, viene utilizzato il file system locale per l'archiviazione file. + +Configurazione richiesta: +``` +# Configurazione Driver File Locale +FILE_LOCAL_ROOT= # Directory radice archiviazione locale, es.: /app/storage/files +FILE_LOCAL_READ_HOST= # Dominio accesso file, es.: https://example.com +FILE_LOCAL_WRITE_HOST= # Dominio caricamento file, es.: https://upload.example.com +``` + +Note: +- `FILE_LOCAL_ROOT`: Specifica il percorso assoluto per l'archiviazione file. Se non configurato, predefinito a `storage/files` sotto la directory radice del progetto +- `FILE_LOCAL_READ_HOST`: URL base per l'accesso ai file +- `FILE_LOCAL_WRITE_HOST`: URL base per il caricamento file. Il sistema aggiunge automaticamente `/api/v1/file/upload` come percorso di caricamento + +### Driver Archiviazione Oggetto Cloud Alibaba (oss) + +Quando `FILE_DRIVER=oss`, viene utilizzato Alibaba Cloud OSS per l'archiviazione file. + +Configurazione richiesta: +``` +# Configurazione Driver File Alibaba Cloud - Privata +FILE_PRIVATE_ALIYUN_ACCESS_ID= # Alibaba Cloud AccessKey ID +FILE_PRIVATE_ALIYUN_ACCESS_SECRET= # Alibaba Cloud AccessKey Secret +FILE_PRIVATE_ALIYUN_BUCKET= # Nome Bucket OSS +FILE_PRIVATE_ALIYUN_ENDPOINT= # Dominio Accesso OSS, es.: oss-cn-hangzhou.aliyuncs.com +FILE_PRIVATE_ALIYUN_ROLE_ARN= # Opzionale, Role ARN per autorizzazione temporanea STS + +# Configurazione Driver File Alibaba Cloud - Pubblica +FILE_PUBLIC_ALIYUN_ACCESS_ID= # Alibaba Cloud AccessKey ID +FILE_PUBLIC_ALIYUN_ACCESS_SECRET= # Alibaba Cloud AccessKey Secret +FILE_PUBLIC_ALIYUN_BUCKET= # Nome Bucket OSS +FILE_PUBLIC_ALIYUN_ENDPOINT= # Dominio Accesso OSS +FILE_PUBLIC_ALIYUN_ROLE_ARN= # Opzionale, Role ARN per autorizzazione temporanea STS +``` + +### Driver Archiviazione Oggetto Cloud ByteDance (tos) + +Quando `FILE_DRIVER=tos`, viene utilizzato ByteDance Cloud TOS per l'archiviazione file. + +Configurazione richiesta: +``` +# Configurazione Driver File ByteDance Cloud - Privata +FILE_PRIVATE_TOS_REGION= # Regione TOS, es.: cn-beijing +FILE_PRIVATE_TOS_ENDPOINT= # Dominio Accesso TOS +FILE_PRIVATE_TOS_AK= # ByteDance Cloud AccessKey +FILE_PRIVATE_TOS_SK= # ByteDance Cloud SecretKey +FILE_PRIVATE_TOS_BUCKET= # Nome Bucket TOS +FILE_PRIVATE_TOS_TRN= # Opzionale, Role ARN per autorizzazione temporanea STS + +# Configurazione Driver File ByteDance Cloud - Pubblica +FILE_PUBLIC_TOS_REGION= # Regione TOS +FILE_PUBLIC_TOS_ENDPOINT= # Dominio Accesso TOS +FILE_PUBLIC_TOS_AK= # ByteDance Cloud AccessKey +FILE_PUBLIC_TOS_SK= # ByteDance Cloud SecretKey +FILE_PUBLIC_TOS_BUCKET= # Nome Bucket TOS +FILE_PUBLIC_TOS_TRN= # Opzionale, Role ARN per autorizzazione temporanea STS +``` + +## 🚀 Inizializzazione Sistema + +### File Icona Predefiniti + +Il sistema include una serie di file icona predefiniti situati nella directory `storage/files/MAGIC/open/default/`. Queste icone verranno caricate nel servizio di archiviazione configurato durante l'inizializzazione del sistema (richiesto solo quando si utilizzano servizi di archiviazione cloud). + +### Comando di Inizializzazione + +Magic Service fornisce uno strumento a riga di comando per inizializzare il file system, specialmente quando si utilizzano servizi di archiviazione cloud per caricare file icona predefiniti nel cloud: + +```bash +php bin/hyperf.php file:init +``` + +Processo di esecuzione del comando: +1. Legge la configurazione corrente del bucket di archiviazione +2. Se si utilizza il file system locale (local), non è necessaria ulteriore inizializzazione +3. Se si utilizza archiviazione cloud (oss o tos), carica file icona predefiniti da locale a archiviazione cloud + +### Caratteristiche di Inizializzazione per Driver + +- **File System Locale (local)**: Non richiesta inizializzazione speciale, il sistema utilizza file di progetto per default +- **Archiviazione Oggetto Cloud Alibaba (oss)**: Richiede comando di inizializzazione per caricare icone predefinite nel bucket OSS +- **Archiviazione Oggetto Cloud ByteDance (tos)**: Richiede comando di inizializzazione per caricare icone predefinite nel bucket TOS + +Esempio output: +``` +Configurazione bucket pubblico: {"adapter":"tos","config":{"region":"cn-beijing","endpoint":"tos-cn-beijing.volces.com","ak":"YOUR_AK","sk":"YOUR_SK","bucket":"magic-public","trn":"YOUR_TRN"},"public_read":true} +Percorso file locale: /path/to/project/storage/files/MAGIC/open/default/icon1.png +Percorso file locale: /path/to/project/storage/files/MAGIC/open/default/icon2.png +... +Inizializzazione file system completata +``` + +## 💡 Scenari d'Uso e Raccomandazioni + +### File System Locale (local) +- Adatto per ambienti di sviluppo o applicazioni piccole +- Non raccomandato per ambienti di produzione a meno di requisiti speciali +- Vantaggi: Configurazione semplice, nessuna dipendenza da terze parti +- Svantaggi: Nessun supporto per deployment distribuito, affidabilità e scalabilità limitate + +### Archiviazione Oggetto Cloud Alibaba (oss) +- Adatto per ambienti di produzione che utilizzano servizi Alibaba Cloud +- Vantaggi: Stabile e affidabile, supporta accelerazione CDN, backup dati e disaster recovery +- Svantaggi: Richiesti costi aggiuntivi + +### Archiviazione Oggetto Cloud ByteDance (tos) +- Adatto per ambienti di produzione che utilizzano servizi ByteDance Cloud +- Vantaggi: Alta integrazione con altri servizi ByteDance Cloud +- Svantaggi: Richiesti costi aggiuntivi + +## 🔒 Raccomandazioni d'Uso Archiviazione Pubblica e Privata + +- **Archiviazione Pubblica**: Adatta per contenuti non sensibili, come immagini sito web, documenti pubblici, ecc. +- **Archiviazione Privata**: Adatta per contenuti protetti, come file privati caricati da utenti, file configurazione sistema, ecc. + +## 📝 Note di Configurazione + +1. Assicurati che tutti gli elementi di configurazione necessari siano riempiti correttamente, altrimenti il sistema non si inizializzerà correttamente +2. Per servizi di archiviazione cloud, assicurati che l'AK/SK configurato abbia permessi sufficienti per operazioni di caricamento file +3. Il comando di inizializzazione dovrebbe essere eseguito una volta durante il primo deployment del sistema, e necessita di essere eseguito nuovamente solo quando si cambia tipo di driver di archiviazione +4. Assicurati che il bucket di archiviazione (Bucket) sia creato in anticipo con policy di accesso corrette + +## ⚠️ Altre Note + +1. Quando si cambia tipo di driver file, assicurati di avere un piano di migrazione per file esistenti +2. I driver Alibaba Cloud OSS e ByteDance Cloud TOS richiedono l'installazione dei rispettivi SDK +3. Utilizza file system locale per ambiente di sviluppo, servizi di archiviazione cloud per ambiente di produzione +4. Configurazioni errate possono causare fallimenti nell'accesso o caricamento file, testa accuratamente prima dell'uso + +## 🛡️ Raccomandazioni di Sicurezza + +1. Ruota regolarmente AccessKey e Secret +2. Utilizza bucket di archiviazione diversi per ambienti diversi +3. Per archiviazione privata, utilizza URL firmati per limitare tempo di accesso (validità firma predefinita sistema è 259200 secondi, circa 3 giorni) +4. Configura policy di accesso cross-origin appropriate (CORS) +5. Non archiviare credenziali di accesso sensibili in repository di codice, utilizza variabili d'ambiente o sistemi di gestione chiavi + +## 🔧 Guida all'Uso API File System + +Magic Service fornisce un set completo di API per operazioni file, principalmente attraverso la classe `FileDomainService`. Ecco API comuni e loro utilizzo: + +### Classi Servizio Core + +- **FileDomainService**: Servizio dominio file, fornisce API di alto livello per tutte le operazioni file +- **CloudFileRepository**: Implementazione repository archiviazione file, responsabile dell'interazione con driver di archiviazione specifici + +### Metodi Comuni + +#### Ottieni Link File + +```php +// Inietta servizio +public function __construct( + private readonly FileDomainService $fileDomainService +) {} + +// Ottieni link singolo file +$fileLink = $this->fileDomainService->getLink( + $organizationCode, // Codice organizzazione + $filePath, // Percorso file + StorageBucketType::Public // Tipo bucket archiviazione (opzionale) +); + +// Accedi informazioni link +if ($fileLink) { + $url = $fileLink->getUrl(); // URL file + $path = $fileLink->getPath(); // Percorso file +} + +// Ottieni link file in batch +$links = $this->fileDomainService->getLinks( + $organizationCode, // Codice organizzazione + [$filePath1, $filePath2], // Array percorsi file + StorageBucketType::Private, // Tipo bucket archiviazione (opzionale) + [$downloadName1, $downloadName2] // Nomi file download (opzionale) +); +``` + +#### Carica File + +```php +// Carica tramite credenziali temporanee (raccomandato per file grandi o caricamento diretto frontend) +$this->fileDomainService->uploadByCredential( + $organizationCode, // Codice organizzazione + new UploadFile( + $localFilePath, // Percorso file locale + $remoteDir, // Directory remota + $fileName, // Nome file + $isStream // Se è dato stream + ), + StorageBucketType::Private, // Tipo bucket archiviazione + true // Se generare automaticamente directory (default true) +); + +// Caricamento diretto (file piccoli) +$this->fileDomainService->upload( + $organizationCode, // Codice organizzazione + new UploadFile( + $localFilePath, // Percorso file locale + $remoteDir, // Directory remota + $fileName, // Nome file + $isStream // Se è dato stream + ), + StorageBucketType::Public // Tipo bucket archiviazione +); +``` + +#### Ottieni URL Pre-firmati + +```php +// Ottieni URL pre-firmati (per accesso temporaneo a file privati) +$preSignedUrls = $this->fileDomainService->getPreSignedUrls( + $organizationCode, // Codice organizzazione + [$fileName1, $fileName2], // Array nomi file + 3600, // Periodo validità (secondi) + StorageBucketType::Private // Tipo bucket archiviazione +); + +// Utilizza URL pre-firmati +foreach ($preSignedUrls as $fileName => $preSignedUrl) { + // Utilizza l'URL pre-firmato +} +``` + +--- + +## Testo Originale in Inglese + # File Driver Usage Guide This document provides detailed information about the file storage drivers supported in the Magic Service project, configuration methods, and usage scenarios. @@ -249,4 +507,5 @@ $preSignedUrls = $this->fileDomainService->getPreSignedUrls( // Use pre-signed URLs foreach ($preSignedUrls as $fileName => $preSignedUrl) { // Use the pre-signed URL -} \ No newline at end of file +} +``` \ No newline at end of file diff --git a/docs/en/development/deploy/super-magic.md b/docs/en/development/deploy/super-magic.md index 88db8e190..9716d92b3 100644 --- a/docs/en/development/deploy/super-magic.md +++ b/docs/en/development/deploy/super-magic.md @@ -1,3 +1,218 @@ +# Guida all'Installazione e all'Uso di Super Magic 🚀 + +Questa guida ti guiderà attraverso l'installazione, la configurazione e l'uso del servizio Super Magic. + +## Prerequisiti + +Prima di iniziare, assicurati che il tuo sistema abbia il seguente software installato: + +- Docker +- Docker Compose +- Git + +## Passi di Installazione + +### 1. Ottieni il Codice del Progetto + +```bash +git clone https://github.com/dtyq/magic.git +cd magic +``` + +### 2. Configura i File di Ambiente + +Il servizio Super Magic dipende da diversi file di configurazione chiave: + +#### 2.1 Crea il File di Configurazione di Super Magic + +```bash +cp config/.env_super_magic.example config/.env_super_magic +``` +Configura le variabili di ambiente di Super Magic. Devi configurare almeno una variabile di ambiente per un modello di linguaggio di grandi dimensioni che supporti il formato OpenAI per il corretto funzionamento. + +Modifica il file `config/.env_super_magic` per configurare le variabili di ambiente necessarie: + +```bash +vim config/.env_super_magic +``` + +### 3. Esegui lo Script di Installazione + +Usa lo script `magic.sh` fornito con il progetto per l'installazione: + +```bash +./bin/magic.sh +``` + +Quando eseguito per la prima volta, lo script di installazione eseguirà le seguenti operazioni: + +1. Rileva la lingua del sistema e ti permette di scegliere la lingua dell'interfaccia (cinese o inglese) +2. Verifica se Docker e Docker Compose sono installati e in esecuzione +3. Rileva l'architettura del sistema e imposta i parametri di piattaforma appropriati +4. Chiede il metodo di distribuzione (distribuzione su computer locale o server remoto) +5. Se selezionata la distribuzione su server remoto, rileva l'IP pubblico e aggiorna le configurazioni correlate +6. Chiede se installare il servizio Super Magic + +Quando ti viene chiesto "Vuoi installare il servizio Super Magic?", seleziona "1" per installare il servizio Super Magic. + +## Guida all'Uso + +### Avvio dei Servizi + +#### Avvia Tutti i Servizi in Primo Piano + +```bash +./bin/magic.sh start +``` + +#### Avvia Tutti i Servizi in Secondo Piano + +```bash +./bin/magic.sh daemon +``` + +#### Avvia Solo il Servizio Super Magic (Primo Piano) + +```bash +./bin/magic.sh super-magic +``` + +#### Avvia Solo il Servizio Super Magic (Secondo Piano) + +```bash +./bin/magic.sh super-magic-daemon +``` + +### Gestione dei Servizi + +#### Visualizza lo Stato del Servizio + +```bash +./bin/magic.sh status +``` + +#### Visualizza i Log del Servizio + +```bash +./bin/magic.sh logs +``` + +#### Riavvia i Servizi + +```bash +./bin/magic.sh restart +``` + +#### Ferma i Servizi + +```bash +./bin/magic.sh stop +``` + +## Dettagli di Configurazione + +### Configurazione dell'Ambiente Super Magic + +Il file `config/.env_super_magic` contiene i seguenti elementi di configurazione importanti: + +#### Configurazione Base +- `APP_ENV`: Impostazione dell'ambiente dell'applicazione, valori possibili includono "test", "production", ecc. +- `LOG_LEVEL`: Livello di log, come INFO, DEBUG, ERROR, ecc. +- `STORAGE_PLATFORM`: Piattaforma di archiviazione, predefinita è "local" + +#### Configurazione delle Chiamate agli Strumenti +- `AGENT_ENABLE_MULTI_TOOL_CALLS`: Se abilitare chiamate multiple agli strumenti (True/False) +- `AGENT_ENABLE_PARALLEL_TOOL_CALLS`: Se abilitare chiamate parallele agli strumenti (True/False) + +#### Configurazione del Modello di Linguaggio di Grandi Dimensioni + +##### Configurazione OpenAI +- `OPENAI_API_BASE_URL`: URL base per l'API OpenAI +- `OPENAI_API_KEY`: Chiave API OpenAI +- `OPENAI_MODEL`: Modello OpenAI predefinito da usare, ad es. "gpt-4o-global" +- `OPENAI_4_1_MODEL`: Nome del modello OpenAI 4.1 +- `OPENAI_4_1_MINI_MODEL`: Nome del modello OpenAI 4.1 Mini +- `OPENAI_4_1_NANO_MODEL`: Nome del modello OpenAI 4.1 Nano + +#### Configurazione del Database Vettoriale +- `QDRANT_COLLECTION_PREFIX`: Prefisso della collezione Qdrant, predefinito è "SUPERMAGIC-" + +#### Configurazione del Browser +- `BROWSER_HEADLESS`: Se il browser funziona in modalità headless (True/False) +- `BROWSER_STORAGE_STATE_TEMPLATE_URL`: URL del template dello stato di archiviazione del browser + +#### Configurazione della Ricerca +- `BING_SUBSCRIPTION_ENDPOINT`: Endpoint dell'API di ricerca Bing +- `BING_SUBSCRIPTION_KEY`: Chiave di sottoscrizione Bing + +#### Configurazione del Servizio Modello + +##### Servizio OpenAI +- `OPENAI_API_KEY`: Chiave API OpenAI +- `OPENAI_API_BASE_URL`: URL base dell'API OpenAI +- `OPENAI_MODEL`: Modello OpenAI da usare + +## Risoluzione dei Problemi + +### Problemi Comuni + +1. **I File di Configurazione Non Esistono** + + Assicurati di aver copiato e configurato correttamente tutti i file di ambiente necessari dai file di esempio: + - `config/.env_sandbox_gateway` + +2. **Fallimento nell'Avvio del Servizio** + + Verifica se il servizio Docker è in esecuzione correttamente: + ```bash + docker info + ``` + + Visualizza i log del servizio per informazioni dettagliate sugli errori: + ```bash + ./bin/magic.sh logs + ``` + +3. **Problemi di Connessione di Rete** + + Se usi la distribuzione remota, assicurati che l'indirizzo IP configurato sia corretto e che le porte rilevanti siano aperte: + - Porte del servizio Super Magic + - Porte del servizio gateway + +## Configurazione Avanzata + +### Distribuzione Personalizzata + +Per scenari di distribuzione personalizzata, puoi modificare il file `.env` per cambiare le seguenti configurazioni: + +- Mappature delle porte dei servizi +- Percorsi di persistenza dei dati +- Limitazioni delle risorse + +### Configurazione Manuale + +Se hai bisogno di configurazioni più granulari manualmente, puoi modificare direttamente il file `docker-compose.yml`. + +## Aggiornamento del Servizio + +Quando hai bisogno di aggiornare il servizio Super Magic, segui questi passi: + +1. Scarica il codice più recente + ```bash + git pull + ``` + +2. Ricostruisci e riavvia i servizi + ```bash + ./bin/magic.sh restart + ``` + +## Conclusione + +Attraverso questa guida, dovresti aver installato e configurato con successo il servizio Super Magic. Se hai domande, consulta la documentazione del progetto o contatta il team di supporto tecnico. + +## Testo Originale in Inglese + # Super Magic Installation and Usage Guide This guide will walk you through how to install, configure, and use the Super Magic service. diff --git a/docs/en/development/quick-start/quick-introduction.md b/docs/en/development/quick-start/quick-introduction.md index 430a8e906..4a0f5b1d9 100644 --- a/docs/en/development/quick-start/quick-introduction.md +++ b/docs/en/development/quick-start/quick-introduction.md @@ -8,6 +8,375 @@
+Magic è un potente motore di innovazione per applicazioni AI di livello enterprise, progettato per aiutare gli sviluppatori a costruire e distribuire rapidamente applicazioni AI. Fornisce un framework di sviluppo completo, una ricca toolchain e best practices, rendendo lo sviluppo di applicazioni AI semplice ed efficiente. + +![flow](https://cdn.letsmagic.cn/static/img/showmagic.jpg) + +## ✨ Caratteristiche + +- 🚀 **Architettura ad Alte Prestazioni**: Sviluppato con PHP+Swow+hyperf, offre eccellenti prestazioni e scalabilità +- 🧩 **Design Modulare**: Sistema di plugin flessibile, supporta estensioni e personalizzazioni rapide +- 🔌 **Supporto Multi-Modello**: Integrazione seamless con modelli AI mainstream, inclusi GPT, Claude, Gemini, ecc. +- 🛠️ **Toolchain di Sviluppo**: Toolchain completa per sviluppo, test e distribuzione +- 🔒 **Sicurezza di Livello Enterprise**: Meccanismi di sicurezza completi, supporta struttura organizzativa e gestione permessi + +## 🚀 Avvio Rapido + +### I. Requisiti di Sistema + +- Sistemi Operativi Supportati: macOS, Linux o Windows +- Docker e Docker Compose installati (fare riferimento alla sezione 3.3 per l'installazione di Docker) +- Connessione di rete (per scaricare immagini e rilevare IP pubblico) +- Git installato (per clonare il codice di Magic) + +### II. Passi di Installazione + +#### 2.1 Clona il Progetto + +```bash +git clone git@github.com:dtyq/magic.git +cd magic +``` + +![git clone magic](https://public-cdn.letsmagic.cn/static/img/git_clone_magic.png) + +#### 2.2. File di Configurazione + +##### File di Configurazione Principali +- .env: File di configurazione principale delle variabili d'ambiente +- config/.env_super_magic: File di configurazione del servizio Super Magic (se scegli di installarlo) +- config/.env_magic_gateway: File di configurazione di Magic Gateway (se scegli di installare Super Magic) +- config/.env_sandbox_gateway: File di configurazione di Sandbox Gateway (se scegli di installare Super Magic) +- Per macOS/Linux, i file mancanti verranno copiati automaticamente durante l'installazione; gli utenti Windows devono copiarli e modificarli manualmente + +##### Configura Manualmente i File e Modifica i Valori Richiesti +```bash +### Per usare Magic, copia .env.example in .env +sudo cp .env.example .env +``` + +##### Riferimento Configurazione Variabili Ambiente Magic: +https://docs.letsmagic.cn/en/development/deploy/environment.html + +```bash +### Per usare i servizi Super Magic, copia i seguenti file: +sudo cp config/.env_super_magic.example config/.env_super_magic +sudo cp config/.env_magic_gateway.example config/.env_magic_gateway +sudo cp config/.env_sandbox_gateway.example config/.env_sandbox_gateway +``` + +##### Riferimento Configurazione Variabili Ambiente Super Magic: +https://docs.letsmagic.cn/en/development/deploy/super-magic.html + +##### Configura IP (Opzionale) +Per il deployment su server remoto, modifica il file .env e sostituisci localhost con il tuo IP server nelle seguenti voci: +``` +MAGIC_SOCKET_BASE_URL=ws://:9502 +MAGIC_SERVICE_BASE_URL=http://:9501 +``` + +Se scegli di installare il servizio Super Magic, assicurati che esistano i seguenti file di configurazione: +- config/.env_super_magic +- config/.env_magic_gateway +- config/.env_sandbox_gateway + +Se config/.env_super_magic non esiste ma config/.env_super_magic.example sì, segui i prompt per copiare e modificare il file. + +#### 2.3. Avvio Servizi su macOS/Linux + +##### macOS/Linux +Esegui lo script di installazione: + +```bash +sudo ./bin/magic.sh start +``` + +##### Windows +Gli utenti Windows possono saltare lo script magic.sh e usare direttamente i comandi docker compose: +In alternativa, puoi scaricare il tool Git [GUI](https://git-scm.com/downloads/win) per un'esperienza di installazione simile a Mac/Linux. + +```bash +# Crea la rete necessaria +docker network create magic-sandbox-network + +# Avvia servizi di base +docker compose up +``` + +Per avviare servizi correlati a Super Magic: + +```bash +docker compose --profile magic-gateway --profile sandbox-gateway up +``` + +#### 2.4. Guida al Processo di Installazione + +##### macOS/Linux +Lo script ti guiderà attraverso i seguenti passi: + +###### Selezione Lingua +- Scegli 1 per Inglese +- Scegli 2 per Cinese +![Selezione Lingua](https://public-cdn.letsmagic.cn/static/img/chose_langugae.png) + +###### Selezione Metodo di Deployment +- Scegli 1 per deployment su computer locale (usando configurazione localhost predefinita) +- Scegli 2 per deployment su server remoto (rileva IP pubblico e chiede se vuoi usarlo) +![Selezione Metodo di Deployment](https://public-cdn.letsmagic.cn/static/img/chose_development_method.png) + +- Nota: Lo script controllerà se magic-sandbox-network è stato creato localmente. Se no, eseguirà automaticamente: +```bash +docker network create magic-sandbox-network +``` + +###### Installazione Servizio Super Magic +- Scegli 1 per installare il servizio Super Magic (richiede pre-configurazione dei file nella directory config/) +- Scegli 2 per non installare il servizio Super Magic +![Installazione Servizio Super Magic](https://public-cdn.letsmagic.cn/static/img/super_magic_service_install.png) + +#### 2.5 Primo Avvio +Dopo il primo avvio, il sistema creerà un file bin/magic.lock (macOS/Linux), e gli avvii successivi salteranno il processo di configurazione di installazione. + +### III. Utilizzo + +#### 3.1 Comandi Comuni + +##### macOS/Linux +```bash +sudo ./bin/magic.sh [command] +``` + +Comandi disponibili: +- start: Avvia servizi in primo piano +- daemon: Avvia servizi in background +- stop: Ferma tutti i servizi +- restart: Riavvia tutti i servizi +- status: Mostra stato servizi +- logs: Mostra log servizi +- super-magic: Avvia solo servizio Super Magic (primo piano) +- super-magic-daemon: Avvia solo servizio Super Magic (background) +- help: Mostra informazioni aiuto + +##### Windows +Gli utenti Windows usano direttamente i comandi docker compose: + +```bash +# Avvia servizi in primo piano +docker compose up + +# Avvia servizi in background +docker compose up -d + +# Ferma servizi +docker compose down + +# Riavvia servizi +docker compose restart + +# Controlla stato servizi +docker compose ps + +# Visualizza log +docker compose logs -f + +# Usa servizio Super Magic (primo piano) +docker compose --profile magic-gateway --profile sandbox-gateway up + +# Usa servizio Super Magic (background) +docker compose --profile magic-gateway --profile sandbox-gateway up -d +``` + +#### 3.2 Esempi + +##### Avvia Servizi +macOS/Linux: +```bash +./bin/magic.sh start +``` + +Windows: +```bash +docker compose up +``` + +##### Avvia Servizi in Background +macOS/Linux: +```bash +./bin/magic.sh daemon +``` + +Windows: +```bash +docker compose up -d +``` + +##### Controlla Stato Servizi +macOS/Linux: +```bash +./bin/magic.sh status +``` + +Windows: +```bash +docker compose ps +``` + +##### Visualizza Log +macOS/Linux: +```bash +./bin/magic.sh logs +``` + +Windows: +```bash +docker compose logs -f +``` + +#### 3.3 Installazione Docker + +##### macOS +1. Visita https://docs.docker.com/desktop/install/mac-install/ +2. Scarica e installa Docker Desktop per Mac +![Scarica e installa Docker Desktop per Mac](https://public-cdn.letsmagic.cn/static/img/install_docker_desktop_for_mac.png) + +3. Avvia l'applicazione Docker Desktop +![Avvia l'applicazione Docker Desktop](https://public-cdn.letsmagic.cn/static/img/start_docker_desktop_application.png) + +##### Linux +1. Visita https://docs.docker.com/engine/install/ +2. Segui le istruzioni di installazione per la tua distribuzione Linux. Ecco un esempio per Ubuntu: +```bash +sudo apt update +# Aggiungi la chiave GPG ufficiale di Docker: +sudo apt-get update +sudo apt-get install ca-certificates curl +sudo install -m 0755 -d /etc/apt/keyrings +sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc +sudo chmod a+r /etc/apt/keyrings/docker.asc + +# Aggiungi il repository alle fonti Apt: +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +sudo apt-get update +``` + ![](https://public-cdn.letsmagic.cn/static/img/ubuntu_system_apt_get_update.png) +```bash +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + ![](https://public-cdn.letsmagic.cn/static/img/ubuntu_system_apt_get_install_docker.png) + +3. Avvia il servizio Docker dopo l'installazione: +```bash +sudo systemctl start docker +``` + +##### Windows +1. Visita https://docs.docker.com/desktop/install/windows-install/ +2. Scarica e installa Docker Desktop per Windows +![Scarica e installa Docker Desktop per Windows](https://public-cdn.letsmagic.cn/static/img/download_docker_desktop_for_windows.png) + +3. Avvia l'applicazione Docker Desktop +4. Assicurati che il backend WSL 2 sia abilitato nelle impostazioni + +### IV. Risoluzione Problemi + +#### Problemi Comuni + +1. **Docker Non in Esecuzione** + - Assicurati che il servizio Docker sia avviato + - macOS: Apri l'applicazione Docker Desktop + - Linux: Esegui `sudo systemctl start docker` + - Windows: Apri l'applicazione Docker Desktop, controlla l'icona nella barra delle applicazioni + +2. **Conflitti di Porta** + - Controlla se altri servizi usano le porte configurate + - Modifica le configurazioni di porta nel file .env + +3. **File di Configurazione Mancanti** + - Segui i prompt per copiare i file di configurazione di esempio e apportare le modifiche necessarie + +4. **Problemi di Rete** + - Assicurati l'accesso a Docker Hub per scaricare le immagini + - Controlla se le impostazioni del firewall bloccano l'accesso alla rete Docker + +5. **Problemi Specifici Windows** + - Assicurati che il supporto WSL 2 sia abilitato + - Se si verificano problemi di permessi, prova a eseguire il prompt dei comandi come amministratore + - Controlla se Windows Firewall blocca il traffico di rete Docker + +6. **Visualizzazione Log** + - Per problemi super-magic, controlla i log dei container che iniziano con sandbox-agent + - Per problemi API, controlla i log del container magic-service + - Per problemi UI frontend, controlla i log del container magic-web + - Per problemi di cross-origin e altri problemi di rete, controlla i log del container magic-caddy + +### V. Disinstallazione + +Per disinstallare il sistema Magic: + +1. Ferma e rimuovi tutti i container + + macOS/Linux: + ```bash + ./bin/magic.sh stop + ``` + + Windows: + ```bash + docker compose down + ``` + +2. Rimuovi la rete Docker (se necessario) + ```bash + docker network rm magic-sandbox-network + ``` + +3. Elimina la directory dei file persistenti ./volumes + +## 📚 Documentazione + +Per documentazione dettagliata, visita il [Centro Documentazione Magic](http://docs.letsmagic.cn/). + +## 🤝 Contributi + +Accogliamo contributi in varie forme, inclusi ma non limitati a: + +- Invio di issue e suggerimenti +- Miglioramento della documentazione +- Invio di correzioni codice +- Contributo di nuove funzionalità + +## 📞 Contattaci + +- Email: bd@dtyq.com +- Sito Web: https://www.letsmagic.cn + +## 🙏 Ringraziamenti + +Grazie a tutti gli sviluppatori che hanno contribuito a Magic! + +
+ +[![Grafico Cronologia Stelle](https://api.star-history.com/svg?repos=dtyq/magic&type=Date)](https://star-history.com/#dtyq/magic&Date) + +
+ +--- + +## Testo Originale in Inglese + +# 🎩 Magic - Next Generation Enterprise AI Application Innovation Engine + +
+ +[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) + + +
+ Magic is a powerful enterprise-grade AI application innovation engine designed to help developers quickly build and deploy AI applications. It provides a complete development framework, rich toolchain, and best practices, making AI application development simple and efficient. ![flow](https://cdn.letsmagic.cn/static/img/showmagic.jpg) @@ -256,16 +625,16 @@ sudo chmod a+r /etc/apt/keyrings/docker.asc # Add the repository to Apt sources: echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ - $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \ - sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ + $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update ``` - ![](https://public-cdn.letsmagic.cn/static/img/ubuntu_system_apt_get_update.png) + ![](https://public-cdn.letsmagic.cn/static/img/ubuntu_system_apt_get_update.png) ```bash sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` - ![](https://public-cdn.letsmagic.cn/static/img/ubuntu_system_apt_get_install_docker.png) + ![](https://public-cdn.letsmagic.cn/static/img/ubuntu_system_apt_get_install_docker.png) 3. Start Docker service after installation: ```bash @@ -285,32 +654,32 @@ sudo systemctl start docker #### Common Issues 1. **Docker Not Running** - - Ensure Docker service is started - - macOS: Open Docker Desktop application - - Linux: Run `sudo systemctl start docker` - - Windows: Open Docker Desktop application, check system tray icon + - Ensure Docker service is started + - macOS: Open Docker Desktop application + - Linux: Run `sudo systemctl start docker` + - Windows: Open Docker Desktop application, check system tray icon 2. **Port Conflicts** - - Check if other services are using the ports configured - - Modify port configurations in the .env file + - Check if other services are using the ports configured + - Modify port configurations in the .env file 3. **Missing Configuration Files** - - Follow the prompts to copy example configuration files and make necessary edits + - Follow the prompts to copy example configuration files and make necessary edits 4. **Network Issues** - - Ensure access to Docker Hub to pull images - - Check if firewall settings are blocking Docker network access + - Ensure access to Docker Hub to pull images + - Check if firewall settings are blocking Docker network access 5. **Windows-Specific Issues** - - Ensure WSL 2 support is enabled - - If permission issues occur, try running the command prompt as administrator - - Check if Windows Firewall is blocking Docker network traffic + - Ensure WSL 2 support is enabled + - If permission issues occur, try running the command prompt as administrator + - Check if Windows Firewall is blocking Docker network traffic 6. **Log Viewing** - - For super-magic issues, check container logs starting with sandbox-agent - - For API issues, check magic-service container logs - - For frontend UI issues, check magic-web container logs - - For cross-origin and other network issues, check magic-caddy container logs + - For super-magic issues, check container logs starting with sandbox-agent + - For API issues, check magic-service container logs + - For frontend UI issues, check magic-web container logs + - For cross-origin and other network issues, check magic-caddy container logs ### V. Uninstallation @@ -318,20 +687,20 @@ To uninstall Magic system: 1. Stop and remove all containers - macOS/Linux: - ```bash - ./bin/magic.sh stop - ``` + macOS/Linux: + ```bash + ./bin/magic.sh stop + ``` - Windows: - ```bash - docker compose down - ``` + Windows: + ```bash + docker compose down + ``` 2. Remove Docker network (if needed) - ```bash - docker network rm magic-sandbox-network - ``` + ```bash + docker network rm magic-sandbox-network + ``` 3. Delete persistent file directory ./volumes diff --git a/docs/en/development/version/changelog.md b/docs/en/development/version/changelog.md index b6ec90695..d7bae6be1 100644 --- a/docs/en/development/version/changelog.md +++ b/docs/en/development/version/changelog.md @@ -1,3 +1,31 @@ +# Registro delle modifiche + +## Aggiornamenti Recenti +1. **Aggiunta del cambio lingua al README** (e3d2732) 🌐 + - Aggiunti collegamenti per il cambio lingua nei file README.md e README_CN.md + - Aggiunta navigazione nel formato `**[English](README.md) | [中文简体](README_CN.md)**` + - Migliorata l'esperienza utente multilingue, facilitando il passaggio tra versioni in lingue diverse + +2. **Unione delle modifiche upstream** (5808dd9, 307d2be, a6138cb) 🔄 + - Unite le ultime modifiche upstream nel ramo corrente + - Mantenuta la sincronizzazione con il repository principale + +3. **Aggiornamento della documentazione** (70218f6) 📚 + - Aggiornati e migliorati la documentazione del progetto + +4. **Aggiunte funzionalità web** + - Implementazione di Web Worker per il controllo delle versioni + - Sistema di rilevamento e notifica degli aggiornamenti della versione frontend + - Supporto per il rilevamento automatico di nuove versioni e invito agli utenti a ricaricare la pagina + - Aggiunti casi di test per garantire il corretto funzionamento + +5. **Inizializzazione del repository** (306b2f66) 🚀 + - Creata la struttura iniziale del progetto + - Aggiunto file README di base + +--- + +## Testo Originale (English) # Changelog ## Recent Updates @@ -21,4 +49,4 @@ 5. **Repository Initialization** (306b2f66) - Created initial project structure - - Added basic README file \ No newline at end of file + - Added basic README file \ No newline at end of file diff --git a/docs/en/development/version/release-planning.md b/docs/en/development/version/release-planning.md index 475ea8f21..6139170aa 100644 --- a/docs/en/development/version/release-planning.md +++ b/docs/en/development/version/release-planning.md @@ -1,3 +1,25 @@ +# Pianificazione delle Release 📅 + +## Ciclo di Vita delle Versioni 🔄 + +| Versione | Stato | Data Fine Supporto Attivo | Data Fine Manutenzione Sicurezza | Data di Rilascio o Previsto | +|----------|------|------------|------------|------------| +| v0.1 | Supporto Attivo | 2026-04-01 | 2027-04-01 | 2025-04-10 | + +* Il supporto attivo include correzioni di bug, correzioni di problemi di sicurezza, iterazioni di funzionalità e aggiunte di funzionalità entro cicli di iterazione regolari; +* La manutenzione di sicurezza include solo correzioni per problemi di sicurezza; +* Le versioni in stato di manutenzione discontinuata non subiranno ulteriori modifiche al codice. Si prega di aggiornare alla versione più recente il prima possibile secondo la guida di aggiornamento per ricevere un supporto migliore; + + +## Ciclo di Iterazione delle Versioni 🔄 + +Magic adotta un modello di sviluppo agile con un piano di iterazione settimanale, rilasciando una versione ogni `Lunedì (UTC/GMT+08:00)`. Questo è solitamente un rilascio di versione z, ma potrebbe anche essere una versione y. Per le versioni x, il piano di iterazione specifico e la timeline saranno determinati in base ai risultati effettivi della ricerca. +Per informazioni sulle regole di versione di Magic, si prega di fare riferimento al capitolo [Descrizione della Versione]. + +--- + +**Testo Originale in Inglese:** + # Release Planning ## Version Lifecycle diff --git a/docs/en/development/version/versions.md b/docs/en/development/version/versions.md index 494cd5e86..f12fe0383 100644 --- a/docs/en/development/version/versions.md +++ b/docs/en/development/version/versions.md @@ -1,3 +1,20 @@ +# 📝 Descrizione Versione + +## 🔢 Regole Versioni + +Magic adotta la regola di numerazione delle versioni x.y.z per denominare ciascuna versione, come la versione 1.2.3, dove 1 è x, 2 è y e 3 è z. Puoi utilizzare questa regola di versioning per pianificare i tuoi aggiornamenti al progetto Magic. +- x rappresenta una versione principale. Quando il core di Magic subisce ampi rifacimenti, o quando ci sono numerosi cambiamenti di rottura nelle API/UI, verrà rilasciata come versione x. I cambiamenti nelle versioni x tipicamente non possono essere compatibili con le versioni x precedenti, sebbene ciò non significhi necessariamente incompatibilità completa. La compatibilità specifica dovrebbe essere determinata in base alla guida di aggiornamento per la versione corrispondente. +- y rappresenta una versione di iterazione principale delle funzionalità. Quando alcune API/UI pubbliche subiscono cambiamenti di rottura, inclusi cambiamenti e cancellazioni di API/UI pubbliche che possono causare incompatibilità con versioni precedenti, verrà rilasciata come versione y. +- z rappresenta una versione di correzione completamente compatibile. Quando si correggono bug o problemi di sicurezza nelle funzionalità esistenti di vari componenti, verrà rilasciata come versione z. Quando un bug impedisce completamente il funzionamento di una funzionalità, potrebbero essere apportati cambiamenti di rottura nelle API anche in una versione z per correggere questo bug. Tuttavia, poiché la funzionalità era precedentemente completamente inutilizzabile, tali cambiamenti non verranno rilasciati come versione y. Oltre alle correzioni di bug, le versioni z possono includere alcune nuove funzionalità o componenti, che non influenzeranno l'uso del codice precedente. + +## ⬆️ Aggiornamento Versioni + +Quando desideri aggiornare le versioni di Magic, se stai aggiornando versioni x e y, segui la guida di aggiornamento per la versione corrispondente nella documentazione. + +--- + +**Testo originale in inglese:** + # Version Description ## Version Rules @@ -9,4 +26,4 @@ Magic adopts the x.y.z version numbering rule to name each version, such as vers ## Upgrading Versions -When you want to upgrade Magic versions, if you are upgrading x and y versions, please follow the upgrade guide for the corresponding version in the documentation. \ No newline at end of file +When you want to upgrade Magic versions, if you are upgrading x and y versions, please follow the upgrade guide for the corresponding version in the documentation. \ No newline at end of file diff --git a/docs/zh/development/quick-start/quick-introduction.md b/docs/zh/development/quick-start/quick-introduction.md index 2d6a7a131..1d350c38c 100644 --- a/docs/zh/development/quick-start/quick-introduction.md +++ b/docs/zh/development/quick-start/quick-introduction.md @@ -1,15 +1,15 @@ -# Magic 入门教程 +# Tutorial Introduttivo Magic -## 一、系统要求 +## I. Requisiti di Sistema -- 支持操作系统：macOS、Linux 或 Windows -- 已安装 Docker 和 Docker Compose（安装 Docker 参考 3.3） -- 网络连接（用于拉取镜像和检测公网 IP） -- 已安装 Git (用于拉取 Magic 代码) +- Sistemi operativi supportati: macOS, Linux o Windows +- Docker e Docker Compose installati (per l'installazione di Docker fare riferimento alla sezione 3.3) +- Connessione di rete (per scaricare immagini e rilevare IP pubblico) +- Git installato (per clonare il codice Magic) -## 二、安装步骤 +## II. Passi di Installazione -### 2.1 克隆项目 +### 2.1 Clonare il Progetto ```bash git clone git@github.com:dtyq/magic.git @@ -19,41 +19,41 @@ cd magic ![git clone magic](https://public-cdn.letsmagic.cn/static/img/git_clone_magic.png) -## 2.2. 配置文件 +## 2.2. Configurazione File -#### 主要配置文件 -- .env：主要环境变量配置文件 -- config/.env_super_magic：Super Magic 服务配置文件（如果选择安装） -- config/.env_magic_gateway：Magic Gateway 配置文件（如果选择安装 Super Magic） -- config/.env_sandbox_gateway：Sandbox Gateway 配置文件（如果选择安装 Super Magic） -- macOS/Linux 安装过程中，如果不存在文件不存在，会自动复制，Windows 需要手动复制修改 +#### File di configurazione principali +- .env: File di configurazione principale delle variabili d'ambiente +- config/.env_super_magic: File di configurazione del servizio Super Magic (se si sceglie di installarlo) +- config/.env_magic_gateway: File di configurazione Magic Gateway (se si sceglie di installare Super Magic) +- config/.env_sandbox_gateway: File di configurazione Sandbox Gateway (se si sceglie di installare Super Magic) +- Durante l'installazione su macOS/Linux, se i file non esistono, verranno copiati automaticamente, su Windows è necessario copiarli e modificarli manualmente -##### 手动配置文件，并修改所需要的值 +##### Configurare manualmente i file e modificare i valori necessari ```bash -# 如需要使用 Magic，复制 .env.example 到 .env +# Se si necessita utilizzare Magic, copiare .env.example in .env sudo cp .env.example .env ``` -##### Magic 环境变量配置参考： +##### Riferimento configurazione variabili d'ambiente Magic: https://docs.letsmagic.cn/zh/development/deploy/environment.html ```bash -# 如需使用 Super Magic 服务，复制以下文件： +# Se si necessita utilizzare il servizio Super Magic, copiare i seguenti file: sudo cp config/.env_super_magic.example config/.env_super_magic sudo cp config/.env_magic_gateway.example config/.env_magic_gateway sudo cp config/.env_sandbox_gateway.example config/.env_sandbox_gateway ``` -##### Super Magic 环境变量配置参考： +##### Riferimento configurazione variabili d'ambiente Super Magic: https://docs.letsmagic.cn/zh/development/deploy/super-magic.html -##### 配置IP（可选） -如果是远程服务器部署，编辑 .env 文件，将以下内容中的 localhost 替换为服务器 IP： +##### Configurazione IP (opzionale) +Se si effettua il deployment su server remoto, modificare il file .env, sostituendo localhost con l'IP del server nel seguente contenuto: ``` -MAGIC_SOCKET_BASE_URL=ws://<服务器IP>:9502 -MAGIC_SERVICE_BASE_URL=http://<服务器IP>:9501 +MAGIC_SOCKET_BASE_URL=ws://:9502 +MAGIC_SERVICE_BASE_URL=http://:9501 ``` -如果您选择安装 Super Magic 服务，请确保以下配置文件存在： +Se si sceglie di installare il servizio Super Magic, assicurarsi che esistano i seguenti file di configurazione: - config/.env_super_magic - config/.env_magic_gateway - config/.env_sandbox_gateway diff --git a/docs/zh/index.md b/docs/zh/index.md index 9ba40a550..f54d2be21 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -2,6 +2,37 @@ # https://vitepress.dev/reference/default-theme-home-page layout: home +hero: + name: "Magic ✨" + text: "Il nuovo motore di innovazione per applicazioni AI a livello enterprise" + tagline: "Crea facilmente potenti applicazioni AI 🚀" + actions: + - theme: brand + text: "Tutorial 📘" + link: /zh/tutorial/magic-info/ + - theme: alt + text: "Documentazione di Sviluppo 🛠️" + link: /zh/development/quick-start/quick-introduction.md + +# features: +# - icon: 🚀 +# title: Veloce ed Efficiente +# details: Con la performance al centro, Magic Docs fornisce siti di documentazione ultraveloce. +# - icon: 🎨 +# title: Design Elegante +# details: Design moderno e pulito che si adatta perfettamente a tutti i dispositivi. +# - icon: 🔧 +# title: Facile da Usare +# details: Configurazione semplice e funzionalità potenti rendono la creazione di documentazione professionale senza sforzo. +--- + +Versione originale (cinese) mantenuta sotto per riferimento: + +```yaml +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + hero: name: "Magic" text: "新一代企业级AI应用创新引擎" @@ -25,4 +56,5 @@ hero: # title: 易于使用 # details: 简单的配置和强大的功能，让创建专业文档变得轻而易举。 --- +``` diff --git a/docs/zh/tutorial/basic/end-node.md b/docs/zh/tutorial/basic/end-node.md index fca30d2fa..1172abc6d 100644 --- a/docs/zh/tutorial/basic/end-node.md +++ b/docs/zh/tutorial/basic/end-node.md @@ -1,3 +1,111 @@ +# 🏁 Nodo Finale + +Il nodo finale è utilizzato per terminare l'esecuzione del flusso. È l'ultimo nodo nel flusso, che segna il completamento del flusso. + +## 📋 Panoramica + +Il nodo finale è utilizzato per chiudere correttamente l'esecuzione del flusso, assicurando che tutte le risorse siano pulite e il flusso sia terminato correttamente. + +## ⚙️ Configurazione + +### Impostazioni Base + +- **Nome**: Identificatore univoco del nodo +- **Descrizione**: Descrizione opzionale dello scopo del nodo +- **Tipo**: Impostato su "finale" (sola lettura) + +### Impostazioni Finale + +1. **Stato Completamento** + - Successo + - Fallimento + - Stato personalizzato + +2. **Opzioni Pulizia** + - Pulizia risorse + - Chiusura connessioni + - Cancellazione cache + +3. **Opzioni Log** + - Sommario esecuzione + - Metriche performance + - Dettagli errore + +## 💡 Esempi di Utilizzo + +### Nodo Finale Base + +```javascript +// Esempio configurazione nodo finale +{ + "type": "end", + "config": { + "status": "success", + "cleanup": true, + "logging": { + "summary": true, + "metrics": true + } + } +} +``` + +### Nodo Finale Errore + +```javascript +// Esempio configurazione nodo finale per gestione errori +{ + "type": "end", + "config": { + "status": "failure", + "errorCode": "${context.error.code}", + "errorMessage": "${context.error.message}", + "cleanup": true, + "logging": { + "summary": true, + "errorDetails": true + } + } +} +``` + +## 🌟 Migliori Pratiche + +1. **Gestione Risorse** + - Pulire tutte le risorse + - Chiudere tutte le connessioni + - Cancellare dati temporanei + +2. **Gestione Errori** + - Registrare dettagli errore + - Impostare stato appropriato + - Includere contesto errore + +3. **Monitoraggio Performance** + - Registrare tempo esecuzione + - Tracciare utilizzo risorse + - Monitorare stato completamento + +## ❓ Problemi Comuni + +1. **Perdita Risorse** + - Verificare esecuzione pulizia + - Controllare chiusura connessioni + - Monitorare utilizzo risorse + +2. **Terminazione Incompleta** + - Controllare processi in sospeso + - Verificare completamento pulizia + - Monitorare risorse sistema + +## 🔗 Nodi Correlati + +- [Nodo Iniziale](./start-node.md) +- [Nodo Risposta](./reply-node.md) +- [Nodo Attesa](./wait-node.md) + +--- + # 结束节点 结束节点用于终止流程执行。它是流程中的最后一个节点，标志着流程的完成。 diff --git a/docs/zh/tutorial/basic/flow/build-a-flow.md b/docs/zh/tutorial/basic/flow/build-a-flow.md index 689c31daf..6938f65b3 100644 --- a/docs/zh/tutorial/basic/flow/build-a-flow.md +++ b/docs/zh/tutorial/basic/flow/build-a-flow.md @@ -1,3 +1,22 @@ +# 🚀 Creare un Flusso +--- +## 📝 Uno, Clicca per Creare Flusso +![create-flow-button](https://cdn.letsmagic.cn/static/img/create-flow-button.png) + +## ⚙️ Due, Impostare Nome e Descrizione del Flusso + +![flow-settings](https://cdn.letsmagic.cn/static/img/flow-settings.png) + +## 🔧 Tre, Orchestrare e Pubblicare il Flusso + +![flow-arrange](https://cdn.letsmagic.cn/static/img/flow-arrange.png) + +## 🤖 Quattro, Utilizzare il Flusso nell'Assistente + +![use-flow](https://cdn.letsmagic.cn/static/img/use-flow.png) + +--- + # 创建一个流程 --- ## 一、点击创建流程 diff --git a/docs/zh/tutorial/basic/flow/use-flow-with-openai.md b/docs/zh/tutorial/basic/flow/use-flow-with-openai.md index 5bb4caaad..ee5e0bc37 100644 --- a/docs/zh/tutorial/basic/flow/use-flow-with-openai.md +++ b/docs/zh/tutorial/basic/flow/use-flow-with-openai.md @@ -1,3 +1,31 @@ +## 🌟 Uno, Spiegazione Sfondo +Dopo aver costruito un flow o un assistente AI, speriamo di poterlo integrare rapidamente con il nostro sistema, il flow fornisce l'accesso API attraverso l'autorizzazione api-key. + +## 🔑 Due, Impostazione API Key +2.1 Entra nella pagina di modifica del flow, clicca su API Key, genera automaticamente l'api key + +![flow_api_image](https://cdn.letsmagic.cn/static/img/flow_api_image.png) + +2.2 Clicca sul pulsante copia, puoi ottenere il comando curl come segue: + +![flow_api_image_2](https://cdn.letsmagic.cn/static/img/flow_api_image_2.png) + +```shell +curl --location +--request POST "https://i-magic-service.letsmagic.cn/api/chat" +--header 'api-key: api-sk-68188*************' +--header 'Content-Type: application/json' +--data-raw '{ +"message": "你是谁", +"conversation_id": "" +}' +``` + +## 📚 Tre, Maggiori API Flow +[https://www.teamshare.cn/knowledge/preview/710857519214628864/775772643732844544](https://www.teamshare.cn/knowledge/preview/710857519214628864/775772643732844544) + +--- + ## 一、背景说明 我们搭建好一个flow或者AI助理之后，希望能跟自己系统快速集成，flow提供了通过api-key授权方式快速提供api方式访问。 ## 二、设置api key diff --git a/docs/zh/tutorial/basic/flow/what-is-flow.md b/docs/zh/tutorial/basic/flow/what-is-flow.md index 0b6133194..6478ce649 100644 --- a/docs/zh/tutorial/basic/flow/what-is-flow.md +++ b/docs/zh/tutorial/basic/flow/what-is-flow.md @@ -1,3 +1,65 @@ +# 🔄 Cosa Sono i Flussi? +--- +Il flusso (Process) è una serie ordinata e correlata di attività o passi, finalizzata a trasformare input (risorse, informazioni) in output di valore per l'utente o l'organizzazione (risultati, prodotti). È il meccanismo centrale del funzionamento organizzativo, che permea i vari campi della produzione, gestione e servizi, attraverso la standardizzazione dei passi, la chiarificazione delle regole e la collaborazione delle risorse, per raggiungere gli obiettivi in modo efficiente. + +## 📋 Uno, Definizione Centrale del Flusso +- **Attività Strutturate:** +Il flusso è composto da molteplici attività interconnesse che devono essere eseguite in ordine logico (come l'acquisto→produzione→controllo qualità→vendita nelle aziende manifatturiere). +- **Input e Output:** +Prende risorse o informazioni come input, dopo elaborazione genera risultati specifici (come ordine cliente→produzione→consegna prodotto). +- **Regole e Standard:** +Il flusso deve seguire norme chiare (come standard operativi, limiti di tempo), per garantire la consistenza dei risultati (come il processo standardizzato di pulizia dei tavoli da McDonald's) + +## 🏗️ Due, Quattro Elementi Fondamentali del Flusso +| Elemento | Spiegazione | Esempio | +| ---------- | --------------------------------------------------------------------- | ------------------------------------ | +| Attività | Unità base del flusso, contiene operazioni concrete (come smistamento pacchi, scrittura codice) | Smistamento→trasporto→consegna nel flusso logistico. | +| Sequenza | Le attività devono essere disposte in ordine logico per evitare confusione (come sviluppo software necessita analisi requisiti→progettazione→codifica→test) | Errore nell'ordine di trasporto dispositivi può causare fallimento assemblaggio | +| Input e Output | L'input è la risorsa che avvia il flusso (come ordine cliente), l'output è il risultato (come consegna prodotto) | Nel flusso ristorazione, l'input è l'ordine, l'output è il piatto. | +| Regole e Standard | Garantiscono il funzionamento stabile del flusso (come i flussi medici devono seguire norme asettiche) | Il rimborso finanziario deve conformarsi agli standard di approvazione aziendale. | + +## 📊 Tre, Classificazione e Scenari dei Flussi +#### Classificazione per Funzione +**Flussi Operativi:** Attività core che creano direttamente valore (come elaborazione ordini, ricerca e sviluppo prodotto). +Flussi di Gestione: Attività di supporto decisionale per il funzionamento operativo (come valutazione performance, formulazione strategia) +Flussi di Supporto: Fornitura di garanzie di base (come manutenzione IT, acquisto attrezzature) + +#### +**Classificazione per Complessità:** +Flussi Semplici: Singolo anello (come approvazione ferie necessita solo revisione responsabile dipartimento). +Flussi Complessi: Collaborazione interdipartimentale (come ricerca e sviluppo nuovo prodotto coinvolge ricerca di mercato, design, produzione, acquisto) + +## 💎 Quattro, Valore e Ruolo dei Flussi + +**Riduzione Ridondanze** +- **Passi Standardizzati**: Attraverso flussi standardizzati si evitano lavori ripetitivi, ad esempio il processo di pulizia tavoli di McDonald's può risparmiare efficacemente tempo. +**Controllo Qualità** +- **Standard Chiari**: Impostare standard chiari in ogni anello, ad esempio controllo rigoroso dei componenti nel processo di produzione automobilistica. +--- +**Promozione Collaborazione e Norme** +**Collaborazione Interdipartimentale** +- **Abbattimento Barriere Dipartimentali**: Realizzazione collaborazione interdipartimentale attraverso gestione flussi, come Huawei che realizza collaborazione di diecimila persone attraverso gestione flussi. +**Riduzione Dipendenze** +- **Conversione Capacità**: Conversione capacità individuale in capacità organizzativa, garanzia che i flussi continuino a funzionare normalmente dopo la partenza dei dipendenti. + +**Miglioramento Flessibilità e Competitività** +- **Risposta Rapida ai Cambiamenti**: Ottimizzazione flussi per adattarsi alla domanda di mercato +- **Costruzione Vantaggio Core**: Standardizzazione flussi forma barriere + +## 🔧 Cinque, Passi Chiave della Gestione Flussi +#### Definizione e Design +- **Chiarire obiettivi, ambito, passi e regole** +#### Esecuzione e Monitoraggio +- **Esecuzione automatizzata attraverso sistemi informativi** +#### Ottimizzazione e Iterazione +- **Analisi colli di bottiglia, miglioramento anelli inefficienti** +![what-is-flow](https://cdn.letsmagic.cn/static/img/markmap.png) + +## 📝 Conclusione +Il flusso è lo "scheletro" del funzionamento organizzativo, attraverso design standardizzato, collaborativo e controllabile, trasforma le risorse in valore. Che si tratti di semplice approvazione o produzione complessa, la gestione efficiente dei flussi può migliorare significativamente la qualità, ridurre i costi e costruire una competitività a lungo termine per l'azienda. + +--- + # 什么是流程？ --- 流程（Process）是一系列有序、关联的活动或步骤，旨在将输入（资源、信息）转化为对用户或组织有价值的输出（结果、产品）。它是组织运作的核心机制，贯穿于生产、管理、服务等各个领域，通过规范步骤、明确规则和协同资源，实现目标的高效达成。 diff --git a/docs/zh/tutorial/basic/node/Cloud-document-parsing.md b/docs/zh/tutorial/basic/node/Cloud-document-parsing.md index 95d4fe34f..8880d70c4 100644 --- a/docs/zh/tutorial/basic/node/Cloud-document-parsing.md +++ b/docs/zh/tutorial/basic/node/Cloud-document-parsing.md @@ -1,4 +1,91 @@ -# 云文档解析节点 +# Nodo Analisi Documenti Cloud ☁️📄 +## Che cos'è il nodo Analisi Documenti Cloud? +Il nodo Analisi Documenti Cloud è un modulo per leggere ed elaborare documenti Markdown archiviati nel cloud. Permette di ottenere e usare direttamente nel flusso i documenti di conoscenza interni dell'azienda, senza copiare-incollare manualmente. Con questo nodo puoi caricare automaticamente il contenuto del documento nel flusso per l'elaborazione a valle. + +Immagine esplicativa: + +L'interfaccia di configurazione comprende l'area di selezione documento, in cui puoi indicare tramite selettore il documento cloud da analizzare. +![云文档解析节点](https://cdn.letsmagic.cn/static/img/Cloud-document-parsing.png) + +## Perché serve? +Nella costruzione di flussi intelligenti spesso bisogna riferirsi/analizzare documenti esistenti. Questo nodo risolve: +1. Automazione acquisizione: lettura automatica dei documenti cloud, niente copia manuale +2. Integrazione della conoscenza: integra la knowledge base interna nei flussi +3. Aggiornamento in tempo reale: quando il documento cambia, il flusso può leggere il contenuto più recente +4. Elaborazione strutturata: converte Markdown in strutture dati utilizzabili dai nodi successivi + +## Scenari d'uso +### Scenario 1: Q&A su knowledge base +Costruisci un sistema Q&A basato su documenti interni: all'interrogazione, estrae info dai documenti e genera la risposta. +### Scenario 2: Analisi contenuto documenti +Analizza automaticamente contenuti, estrae chiavi/metriche o genera report riassuntivi. +### Scenario 3: Alert aggiornamento documenti +Monitora documenti critici e notifica quando ci sono aggiornamenti con changelog o sommario. + +## Parametri del nodo +### Input +|Nome|Descrizione|Obbligatorio|Default| +|---|---|---|---| +|Selettore documento|Scegli il documento cloud da analizzare|Sì|—| + +### Output +|Nome|Descrizione|Tipo| +|---|---|---| +|Contenuto (content)|Testo del documento analizzato|Stringa| + +## Istruzioni d'uso +### Passi base +1. Aggiungi il nodo al canvas dall'elenco nodi +2. Seleziona documento: + 1. Dal menu a discesa scegli direttamente il documento cloud da analizzare +3. Collega i nodi a valle: collega l'output a nodi di elaborazione successivi + +### Suggerimenti avanzati +1. Selezione dinamica: passa l'ID documento come variabile per scegliere dinamicamente +2. Estrazione mirata: insieme al nodo codice estrai sezioni specifiche +3. Multi-documento: usa un ciclo per elaborare più documenti in batch +4. Diff contenuti: confronta versioni diverse con logiche personalizzate nel nodo codice + +## Note +### Permessi di accesso +Assicurati che l'esecutore del flusso abbia accesso al documento selezionato. +### Dimensione documenti +Documenti molto grandi possono impattare le performance; valuta split o pre-estrazioni. +### Supporto Markdown +Supporta Markdown standard; formati speciali/custom potrebbero non essere interpretati correttamente. +### Tempistiche +Si legge il contenuto al momento dell'esecuzione; per documenti che cambiano spesso valuta una cache. + +## FAQ +### Il documento non si visualizza o analizza correttamente +Soluzioni: +- Verifica la conformità del formato Markdown +- Verifica caratteri speciali/encoding +- Verifica i permessi sul documento + +### Come gestire immagini e allegati? +Soluzioni: +- Il nodo estrae solo testo per default +- Per immagini usa un nodo Richiesta HTTP per recuperarle +- Per allegati usa API dedicate ai file + +### Come trattare tabelle formattate? +Soluzioni: +- Le tabelle Markdown vengono estratte come testo +- Converti in strutture con un nodo codice a valle +- Per casi complessi valuta il nodo analisi fogli di calcolo + +## Nodi spesso abbinati +|Tipo|Motivo| +|---|---| +|Chiamata LLM|Riassumere, rispondere, estrarre info dal contenuto +|Segmentazione testo|Spezzare testi lunghi in chunk +|Codice|Trasformazioni/estrazioni personalizzate +|Ricerca conoscenza|Q&A basato su vettori e similarità + +--- + +# 中文原文 ## 什么是云文档解析节点？ 云文档解析节点是一个专门用于读取和处理云端存储的Markdown文档的功能模块。它能够帮助您直接在工作流中获取和使用企业内部的知识文档，无需手动复制粘贴文档内容。通过此节点，您可以将文档内容自动加载到工作流中，以便后续节点进行处理和分析。 @@ -76,4 +163,4 @@ |大模型调用节点|将解析的文档内容传入大模型，生成摘要、回答问题或提取关键信息| |文本切割节点|将长文档切割成小段落，便于进一步处理| |代码节点|对文档内容进行格式转换、数据提取或自定义处理| -|知识检索节点|结合向量搜索，实现基于文档内容的智能问答| \ No newline at end of file +|知识检索节点|结合向量搜索，实现基于文档内容的智能问答| diff --git a/docs/zh/tutorial/basic/node/Code-execution.md b/docs/zh/tutorial/basic/node/Code-execution.md index 86c642a8c..031e15cbe 100644 --- a/docs/zh/tutorial/basic/node/Code-execution.md +++ b/docs/zh/tutorial/basic/node/Code-execution.md @@ -1,42 +1,215 @@ -# 代码执行节点 +# Nodo Esecuzione Codice 🚀 + +## Che cos'è il Nodo Esecuzione Codice? + +Il Nodo Esecuzione Codice è uno strumento potente che permette di scrivere ed eseguire frammenti di codice personalizzati all'interno del flusso di lavoro. Attraverso questo nodo, è possibile utilizzare linguaggi di programmazione (attualmente supportati PHP e Python) per elaborare dati, eseguire calcoli o implementare logiche complesse che altri nodi non possono gestire direttamente. È come avere un piccolo ambiente di programmazione integrato nel flusso di lavoro, che offre flessibilità per affrontare varie esigenze speciali. + +**Spiegazione Immagine:** + +L'interfaccia del Nodo Esecuzione Codice è composta principalmente da tre parti: la zona di input del nodo in alto, l'area di modifica del codice al centro, e la zona di configurazione dell'output in basso. Nell'area di modifica del codice, è possibile scrivere direttamente il codice; in alto e in basso, è possibile impostare i parametri di input necessari al codice e i parametri di output generati. +![Nodo Esecuzione Codice](https://cdn.letsmagic.cn/static/img/20250408165220.jpg) + +## Perché serve il Nodo Esecuzione Codice? + +Durante la costruzione dei flussi di lavoro, potresti incontrare queste situazioni: +1. **Elaborazione dati complessa**: Necessità di trasformare, calcolare o riorganizzare dati in modi complessi +2. **Logica condizionale**: Implementare giudizi condizionali più complessi rispetto ai semplici nodi di diramazione +3. **Funzionalità personalizzate**: Implementare funzionalità specifiche che altri nodi non possono fornire direttamente +4. **Algoritmi speciali**: Applicare algoritmi o formule aziendali specifici + +Il Nodo Esecuzione Codice è progettato per risolvere queste situazioni. Permette di liberarsi dalle limitazioni delle funzionalità preimpostate, implementando logiche completamente personalizzate attraverso la programmazione. + +## Scenari di Applicazione + +### 1. Conversione Formato Dati +Quando è necessario convertire i dati ottenuti dalle API in formati specifici, o combinare dati da molteplici fonti in una struttura unificata, il Nodo Esecuzione Codice può gestire facilmente queste conversioni. + +### 2. Calcoli Complessi +Per scenari che coinvolgono calcoli multi-step, elaborazione ciclica o l'uso di algoritmi specifici, il Nodo Esecuzione Codice può implementare logiche di calcolo di qualsiasi complessità. + +### 3. Giudizi di Regole Personalizzate +Quando le regole aziendali sono complesse e non possono essere espresse con semplici nodi condizionali, il Nodo Esecuzione Codice può implementare logiche di giudizio multi-condizione e multi-livello. + +## Spiegazione Parametri del Nodo + +### Parametri Base + +|Nome Parametro|Descrizione|Obbligatorio|Valore Default| +|---|---|---|---| +|Linguaggio Codice|Selezionare il linguaggio di esecuzione del codice, supporta PHP e Python|Sì|PHP| +|Modalità Codice|Selezionare la modalità di origine del codice, può essere scrittura diretta o importazione variabile|Sì|Scrittura Diretta| +|Contenuto Codice|Il frammento di codice da eseguire|Sì|Vuoto| +|Importa Codice|Quando si seleziona la modalità "Importa Variabile", specificare la variabile che contiene il codice|Obbligatorio solo in modalità importazione|Nessuno| +|Parametri Input|Il Nodo Esecuzione Codice può ricevere dati passati dai nodi upstream come input. È possibile aggiungere e configurare questi parametri nella scheda "Input" del nodo|Sì|Nessuno| +|Parametri Output|Il risultato dell'esecuzione del codice può essere configurato come parametri di output, da passare ai nodi downstream. È possibile aggiungere e configurare questi parametri nella scheda "Output" del nodo|Sì|Nessuno| + +### Spiegazione Tipi di Dati + +I parametri di input e output supportano molteplici tipi di dati: +- Stringa +- Numero +- Booleano +- Array +- Oggetto +- Array di Stringhe +- Array di Interi +- Array di Booleani +- Array di Oggetti +- Valore Numerico +- Array di Valori Numerici + +## Istruzioni per l'Uso + +### Passi di Configurazione Base + +1. **Aggiungere Nodo Esecuzione Codice**: Nell'editor del flusso di lavoro, trascinare il nodo "Esecuzione Codice" sulla tela. +2. **Selezionare Linguaggio Codice**: Cliccare sul nodo, nel pannello delle proprietà a destra selezionare il linguaggio del codice (PHP o Python). +3. **Scrivere Codice**: + 1. Se si seleziona la modalità "Scrittura Diretta", inserire il codice nell'editor di codice + 2. Se si seleziona la modalità "Importa Variabile", selezionare la variabile che contiene il codice +4. **Configurare Parametri Input**: + 1. Cliccare sulla scheda "Input" + 2. Cliccare il pulsante "Aggiungi Parametro" + 3. Impostare nome parametro, tipo e valore +5. **Configurare Parametri Output**: + 1. Cliccare sulla scheda "Output" + 2. Cliccare il pulsante "Aggiungi Parametro" + 3. Impostare nome parametro e tipo +6. **Connettere Nodi**: Connettere i nodi upstream al nodo di esecuzione codice, e il nodo di esecuzione codice ai nodi downstream. +7. **Salvare Flusso di Lavoro**: Cliccare il pulsante di salvataggio per salvare la configurazione. + +### Tecniche Avanzate + +#### Esempio Codice PHP +In modalità PHP, il codice riceverà i parametri di input come variabili e fornirà l'output attraverso un array di ritorno: +```php += 18; +$message = $isAdult ? "Sei maggiorenne." : "Non sei maggiorenne."; + +// Restituire risultato (diventerà parametro di output) +return [ + 'greeting' => $greeting, + 'isAdult' => $isAdult, + 'message' => $message +]; +``` + +#### Esempio Codice Python +In modalità Python, il codice riceverà i parametri di input come variabili e fornirà l'output definendo variabili globali: +```python +# Ottenere parametri di input +name = globals().get('name', 'Ospite') +age = globals().get('age', 0) + +# Logica di elaborazione +greeting = f"Ciao, {name}!" +is_adult = age >= 18 +message = "Sei maggiorenne." if is_adult else "Non sei maggiorenne." + +# Impostare parametri di output (diventeranno variabili globali) +globals()['greeting'] = greeting +globals()['is_adult'] = is_adult +globals()['message'] = message +``` + +## Note Importanti + +### Limitazioni di Sicurezza del Codice + +1. **Limite Tempo Esecuzione**: L'esecuzione del codice ha un limite di tempo, codici che richiedono molto tempo potrebbero essere interrotti. +2. **Limitazioni Risorse**: L'ambiente di esecuzione ha memoria e capacità di elaborazione limitate, evitare operazioni troppo complesse o intensive in risorse. +3. **Limitazioni Accesso**: Per motivi di sicurezza, l'ambiente di esecuzione del codice non può accedere direttamente al file system o effettuare richieste di rete. + +### Tecniche di Debug + +1. **Output Informazioni Debug**: Usare `echo` in PHP o `print` in Python per output di informazioni di debug, queste informazioni verranno mostrate nei log di esecuzione del nodo. +2. **Test Graduale**: Logiche complesse dovrebbero essere scomposte in piccoli passi, testare gradualmente per garantire che ogni parte sia corretta. +3. **Validazione Dati**: Aggiungere controlli all'inizio del codice per validare l'esistenza e la correttezza dei parametri di input. + +## Domande Frequenti + +### Perché il mio codice non viene eseguito correttamente? + +1. **Controllare Errori Sintassi**: Assicurarsi che il codice non abbia errori di sintassi, come punti e virgola mancanti, parentesi non corrispondenti, ecc. +2. **Controllare Nomi Variabili**: Assicurarsi che i nomi dei parametri di input referenziati nel codice corrispondano esattamente ai nomi dei parametri di input configurati, inclusi maiuscole e minuscole. +3. **Controllare Formato Ritorno**: Assicurarsi che il codice PHP restituisca correttamente l'array, o che il codice Python imposti correttamente le variabili globali. + +### Come utilizzare i risultati dei nodi upstream nel codice? + +1. **Configurare Parametri Input**: Prima aggiungere nella scheda "Input" i parametri corrispondenti ai risultati dei nodi upstream. +2. **Referenziare Valori Variabili**: Impostare il valore del parametro come variabile di output del nodo upstream. +3. **Utilizzare nel Codice**: Nel codice referenziare direttamente questi parametri di input attraverso il nome della variabile. + +## Migliori Pratiche + +### Nodi di Combinazione Comuni + +|Tipo Nodo|Motivo Combinazione| +|---|---| +|Nodo Diramazione Condizionale|Il Nodo Esecuzione Codice può elaborare logiche complesse, poi passare i risultati al Nodo Diramazione Condizionale per il giudizio.| +|Nodo Richiesta HTTP|Elaborare i dati restituiti dalle richieste API, effettuare conversioni di formato o estrarre informazioni chiave.| +|Nodo Chiamata Modello Grande|Elaborare i contenuti generati dal modello grande, come estrarre informazioni specifiche, formattare o classificare.| + +--- + +# 中文原文 + ## 什么是代码执行节点？ -代码执行节点是一个强大的工具，它允许您在工作流中编写和执行自定义代码片段。通过这个节点，您可以用编程语言（目前支持PHP和Python）处理数据、执行计算或实现其他节点无法直接实现的复杂逻辑。就像是在工作流中嵌入了一个小型的编程环境，让您能够灵活地应对各种特殊需求。 -**图片说明：** +代码执行节点是一个强大的工具，允许在工作流中编写并执行自定义代码片段。通过该节点，可以使用编程语言（当前支持 PHP 和 Python）对数据进行处理、计算，或实现其他节点无法直接完成的复杂逻辑。它就像工作流中的一个小型编程环境，为应对各种特殊需求提供了灵活性。 + +图片说明： -代码执行节点界面主要由三部分组成：顶部为节点输入区，中间的代码编辑区，以及底部的输出配置区。在代码编辑区，您可以直接编写代码；在顶部和底部，您可以设置代码需要的输入参数和生成的输出参数。 +代码执行节点界面主要由三部分组成：上方的节点输入区、中间的代码编辑区以及下方的输出配置区。在代码编辑区可以直接编写代码；在上下区域可以分别配置代码所需的输入参数与产出的输出参数。 ![代码执行节点](https://cdn.letsmagic.cn/static/img/20250408165220.jpg) ## 为什么需要代码执行节点？ -在构建工作流时，您可能会遇到这些情况： -1. **复杂数据处理**：需要对数据进行复杂的转换、计算或结构调整 -2. **条件逻辑**：需要实现比简单分支节点更复杂的条件判断 -3. **自定义功能**：需要实现其他节点无法直接提供的特定功能 -4. **特殊算法**：需要应用特定的业务算法或公式 -代码执行节点就是为解决这些情况而设计的。它让您摆脱预设功能的限制，通过编程实现完全自定义的逻辑。 + +在构建工作流时，可能会遇到如下场景： +1. 复杂数据处理：需要对数据进行复杂的转换、计算或重组 +2. 条件逻辑控制：实现比简单分支更复杂的条件判断 +3. 自定义功能：实现其他节点无法直接提供的特定功能 +4. 特殊算法：应用某些业务专用的算法或公式 + +代码执行节点正是为了解决这些情况而设计。它让我们摆脱预设功能的限制，通过编程实现完全自定义的业务逻辑。 + ## 适用场景 + ### 1. 数据格式转换 -当您需要将从API获取的数据转换为特定格式，或者将多个来源的数据组合成统一结构时，代码执行节点可以轻松处理这些转换工作。 +当需要将 API 获取的数据转换为特定结构，或者将来自多来源的数据合并为统一结构时，代码执行节点可以轻松处理这些转换。 + ### 2. 复杂计算 -对于涉及多步骤计算、需要循环处理或使用特定算法的场景，代码执行节点可以实现任何复杂度的计算逻辑。 +对于涉及多步计算、循环处理或使用特定算法的场景，代码执行节点都可以实现任意复杂度的计算逻辑。 + ### 3. 自定义规则判断 -当业务规则复杂，无法用简单条件节点表达时，代码执行节点可以实现多条件、多层次的复杂判断逻辑。 +当业务规则较复杂，无法用简单的条件分支表达时，代码执行节点可以实现多条件、多层级的判断逻辑。 + ## 节点参数说明 -### 基本参数 -|参数名称|描述|是否必填|默认值| + +### 基础参数 + +|参数名|说明|是否必填|默认值| |---|---|---|---| -|代码语言|选择代码的执行语言，支持PHP和Python|是|PHP| -|代码模式|选择代码的来源方式，可以是直接编写或导入变量|是|直接编写| +|代码语言|选择代码运行语言，支持 PHP 和 Python|是|PHP| +|代码模式|选择代码来源方式，可为直接书写或变量导入|是|直接书写| |代码内容|需要执行的代码片段|是|空| -|导入代码|当选择"导入变量"模式时，指定包含代码的变量|仅导入模式必填|无| -|输入参数|代码执行节点可以接收上游节点传递的数据作为输入。您可以在节点的"输入"标签页中添加和配置这些参数|是|无| -|输出参数|代码执行的结果可以配置为输出参数，传递给下游节点使用。您可以在节点的"输出"标签页中添加和配置这些参数|是|无| +|导入代码|选择“变量导入”模式时，指定承载代码的变量|仅在导入模式必填|无| +|输入参数|可在“输入”配置页添加并配置，接收上游节点传入的数据|是|无| +|输出参数|可在“输出”配置页添加并配置，将运行结果传递给下游|是|无| ### 数据类型说明 -输入、输出参数支持多种数据类型： + +输入与输出参数支持多种类型： - 字符串 - 数字 -- 布尔值 +- 布尔 - 数组 - 对象 - 字符串数组 @@ -45,26 +218,29 @@ - 对象数组 - 数值 - 数值数组 + ## 使用说明 + ### 基本配置步骤 -1. **添加代码执行节点**：在工作流编辑器中，拖拽"代码执行"节点到画布上。 -2. **选择代码语言**：点击节点，在右侧属性面板中选择代码语言（PHP或Python）。 -3. **编写代码**： - 1. 如果选择"直接编写"模式，在代码编辑器中输入您的代码 - 2. 如果选择"导入变量"模式，选择包含代码的变量 -4. **配置输入参数**： - 1. 点击"输入"标签页 - 2. 点击"添加参数"按钮 - 3. 设置参数名、类型和值 -5. **配置输出参数**： - 1. 点击"输出"标签页 - 2. 点击"添加参数"按钮 - 3. 设置参数名和类型 -6. **连接节点**：将上游节点连接到代码执行节点，将代码执行节点连接到下游节点。 -7. **保存工作流**：点击保存按钮保存您的配置。 + +1. 添加代码执行节点：在画布中拖入“代码执行”节点 +2. 选择语言：在右侧属性面板选择 PHP 或 Python +3. 编写/导入代码： + 1. 选择“直接书写”时，在编辑器中输入代码 + 2. 选择“变量导入”时，选择承载代码的变量 +4. 配置输入参数： + 1. 切换到“输入”页 + 2. 点击“添加参数”，设置名称、类型与取值 +5. 配置输出参数： + 1. 切换到“输出”页 + 2. 点击“添加参数”，设置名称与类型 +6. 连接上下游节点：将上游输出连入本节点，并将本节点输出连接至下游 +7. 保存：点击保存按钮保存配置 + ### 进阶技巧 + #### PHP 代码示例 -在PHP模式下，您的代码将接收输入参数作为变量，并通过返回数组的方式提供输出： +在 PHP 模式下，代码通过返回数组的方式输出结果： ```php = 18; -$message = $isAdult ? "您已成年。" : "您未成年。"; +$message = $isAdult ? "已成年。" : "未成年。"; -// 返回结果（会成为输出参数） +// 返回结果（作为输出参数） return [ 'greeting' => $greeting, 'isAdult' => $isAdult, 'message' => $message ]; ``` + #### Python 代码示例 -在Python模式下，您的代码将接收输入参数作为变量，并通过定义全局变量的方式提供输出： +在 Python 模式下，通过设置全局变量的方式输出结果： ```python # 获取输入参数 name = globals().get('name', '访客') age = globals().get('age', 0) # 处理逻辑 -greeting = f"你好，{name}！" +greeting = f"你好，{name}!" is_adult = age >= 18 -message = "您已成年。" if is_adult else "您未成年。" +message = "已成年。" if is_adult else "未成年。" -# 设置输出参数（会成为全局变量） +# 设置输出参数（作为全局变量） globals()['greeting'] = greeting globals()['is_adult'] = is_adult globals()['message'] = message ``` + ## 注意事项 -### 代码安全限制 -1. **执行时间限制**：代码执行有时间限制，长时间运行的代码可能会被中断。 -2. **资源限制**：执行环境的内存和处理能力有限，请避免过于复杂或资源密集型的操作。 -3. **访问限制**：出于安全考虑，代码执行环境不能直接访问文件系统或进行网络请求。 + +### 安全限制 + +1. 执行超时：代码运行有时间限制，长时间运行会被中断 +2. 资源限制：执行环境的内存与算力有限，避免过于复杂或高开销操作 +3. 访问限制：出于安全考虑，运行环境不可直接访问文件系统或发起网络请求 + ### 调试技巧 -1. **输出调试信息**：在PHP中使用`echo`或在Python中使用`print`输出调试信息，这些信息会显示在节点的执行日志中。 -2. **分步测试**：复杂逻辑应分解为小步骤，逐步测试确保每部分正确。 -3. **数据验证**：在代码开始处添加检查，验证输入参数的存在性和正确性。 + +1. 调试输出：PHP 使用 `echo`、Python 使用 `print` 输出调试信息，可在节点执行日志查看 +2. 逐步测试：复杂逻辑建议拆分为小步骤，逐步验证 +3. 数据校验：在代码开头添加参数校验，确保输入存在且格式正确 + ## 常见问题 -### 为什么我的代码没有正确执行？ -1. **检查语法错误**：确保您的代码没有语法错误，例如缺少分号、括号不匹配等。 -2. **检查变量名称**：确保代码中引用的输入参数名称与配置的输入参数名称完全一致，包括大小写。 -3. **检查返回格式**：确保PHP代码正确返回数组，或Python代码正确设置全局变量。 -### 如何在代码中使用上游节点的结果？ -1. **配置输入参数**：首先在"输入"标签页中添加与上游节点结果对应的参数。 -2. **引用变量值**：将参数值设置为上游节点的输出变量。 -3. **在代码中使用**：在代码中通过变量名直接引用这些输入参数。 + +### 代码未正确执行怎么办？ +1. 检查语法错误：如分号、括号是否匹配等 +2. 检查变量名：代码引用的输入变量需与“输入”参数配置完全一致（区分大小写） +3. 检查返回格式：PHP 需返回数组；Python 需正确设置全局变量 + +### 如何在代码中使用上游结果？ +1. 在“输入”页添加与上游结果对应的参数 +2. 将参数值配置为上游节点的输出变量 +3. 在代码中直接以变量名使用 + ## 最佳实践 + ### 常见搭配节点 -|**节点类型**|**搭配原因**| + +|节点类型|搭配原因| |---|---| -|条件分支节点|代码执行节点可以处理复杂逻辑，然后将结果传给条件分支节点进行判断。| -|HTTP请求节点|处理API请求返回的数据，进行格式转换或提取关键信息。| -|大模型调用节点|对大模型生成的内容进行处理，如提取特定信息、格式化或分类。| \ No newline at end of file +|条件分支节点|先由代码节点处理复杂逻辑，再交由分支判断| +|HTTP 请求节点|对 API 响应数据做二次处理、格式转换或关键信息提取| +|大模型调用节点|对大模型产出的文本做进一步抽取、格式化或分类| diff --git a/docs/zh/tutorial/basic/node/Create-group-chat.md b/docs/zh/tutorial/basic/node/Create-group-chat.md index 149819797..1a62ac7d6 100644 --- a/docs/zh/tutorial/basic/node/Create-group-chat.md +++ b/docs/zh/tutorial/basic/node/Create-group-chat.md @@ -1,124 +1,156 @@ -# 创建群聊节点 -## 什么是创建群聊节点？ -创建群聊节点是 Magic Flow 中专门用于创建多人聊天群组的功能节点。通过该节点，您可以在工作流程中自动创建各类型的群聊，如内部工作群、项目群、培训群等，并可自动添加指定成员。就像您在日常使用的社交软件中手动创建群聊一样，但这一过程可以在工作流中自动完成。 - -**图片说明：** - -创建群聊节点界面包含群名称、群主、群成员、群类型等配置项，以及将当前用户和助理添加进群聊的选项。您可以通过简单的配置，自动创建满足业务需求的各类群聊。 -![创建群聊节点](https://cdn.letsmagic.cn/static/img/Create-group-chat.png) - - -## 为什么需要创建群聊节点？ -在智能工作流中，自动创建群聊可以解决许多实际问题： -1. **自动化协作流程**：当新项目启动、新客户加入或新任务创建时，自动组建相关工作群，保证信息传递及时有效。 -2. **规范化沟通渠道**：按照预设模板创建标准化的群聊，确保组织内部沟通渠道的一致性和规范性。 -3. **提升响应速度**：在特定事件触发时自动创建群聊并添加相关人员，减少人工创建群聊的时间，提高工作效率。 -4. **智能化群成员管理**：根据业务规则自动添加合适的成员，避免漏加人员或添加错误人员的情况。 -## 适用场景 -### 场景一：新项目启动自动建群 -当有新项目立项时，自动创建项目群，并将项目经理设为群主，添加项目团队成员和相关部门负责人到群中，同时让项目助手机器人发送项目启动通知。 -### 场景二：客户服务流程 -当新客户注册或提交特定服务请求时，自动创建服务群，添加客户、客服人员和相关专家，使客户问题能够在专属群聊中得到高效解决。 -### 场景三：培训课程组织 -培训系统可以为每个新课程自动创建培训群，添加讲师、学员和课程助教，并由助手机器人发送课程介绍和学习资料。 -## 节点参数说明 -### 输入参数 -|参数名称|说明|是否必填|示例值| +# Nodo Creazione Chat di Gruppo 👥 + +## Che cos'è il Nodo Creazione Chat di Gruppo? + +Il Nodo Creazione Chat di Gruppo è un nodo funzionale specializzato in Magic Flow per creare gruppi di chat multi-utente. Attraverso questo nodo, è possibile creare automaticamente vari tipi di chat di gruppo nel flusso di lavoro, come gruppi di lavoro interni, gruppi di progetto, gruppi di formazione, ecc., e aggiungere automaticamente membri specificati. È come creare manualmente una chat di gruppo nel software di social networking che si usa quotidianamente, ma questo processo può essere completato automaticamente nel flusso di lavoro. + +**Spiegazione Immagine:** + +L'interfaccia del Nodo Creazione Chat di Gruppo include elementi di configurazione come nome del gruppo, proprietario del gruppo, membri del gruppo, tipo di gruppo, e opzioni per aggiungere l'utente corrente e l'assistente alla chat di gruppo. È possibile creare automaticamente vari tipi di chat di gruppo che soddisfano le esigenze aziendali attraverso una configurazione semplice. +![Nodo Creazione Chat di Gruppo](https://cdn.letsmagic.cn/static/img/Create-group-chat.png) + +## Perché serve il Nodo Creazione Chat di Gruppo? + +Nel flusso di lavoro intelligente, la creazione automatica di chat di gruppo può risolvere molti problemi pratici: +1. **Automazione dei processi di collaborazione**: Quando si avvia un nuovo progetto, si unisce un nuovo cliente o si crea una nuova attività, viene automaticamente formato un gruppo di lavoro correlato, garantendo che il passaggio delle informazioni sia tempestivo ed efficace. +2. **Standardizzazione dei canali di comunicazione**: Creare chat di gruppo standardizzate secondo modelli preimpostati, garantendo la consistenza e la standardizzazione dei canali di comunicazione interni all'organizzazione. +3. **Miglioramento della velocità di risposta**: Creare automaticamente chat di gruppo e aggiungere personale correlato quando vengono attivati eventi specifici, riducendo il tempo per la creazione manuale di chat di gruppo e migliorando l'efficienza lavorativa. +4. **Gestione intelligente dei membri del gruppo**: Aggiungere automaticamente membri appropriati secondo le regole aziendali, evitando di dimenticare persone o aggiungere persone errate. + +## Scenari di Applicazione + +### Scenario 1: Creazione Automatica Gruppo per Avvio Nuovo Progetto +Quando viene approvato un nuovo progetto, creare automaticamente un gruppo di progetto, impostare il project manager come proprietario del gruppo, aggiungere membri del team di progetto e responsabili dei dipartimenti correlati al gruppo, e far sì che il robot assistente di progetto invii notifiche di avvio progetto. + +### Scenario 2: Processo Servizio Clienti +Quando un nuovo cliente si registra o presenta una richiesta di servizio specifica, creare automaticamente un gruppo di servizio, aggiungere cliente, personale di servizio e esperti correlati, in modo che i problemi del cliente possano essere risolti efficientemente nella chat di gruppo dedicata. + +### Scenario 3: Organizzazione Corsi di Formazione +Il sistema di formazione può creare automaticamente un gruppo di formazione per ogni nuovo corso, aggiungere docente, studenti e assistenti del corso, e far sì che il robot assistente invii introduzione del corso e materiali di studio. + +## Spiegazione Parametri del Nodo + +### Parametri di Input + +|Nome Parametro|Spiegazione|Obbligatorio|Valore Esempio| |---|---|---|---| -|群名称|设置创建的群聊名称|是|"项目A开发小组"| -|群主|设置群聊的管理者，必须指定一位用户作为群主|是|用户变量或直接选择| -|群成员|需要添加到群聊中的其他成员列表|否|用户数组或直接选择| -|群类型|选择群聊类型，不同类型群聊可能有不同权限设置|是|内部群、项目群等| -|将当前用户添加进群聊|是否将触发工作流的用户添加到群聊中|否（默认开启）|勾选或取消勾选| -|将当前助理添加进群聊|是否将当前工作流的AI助理添加到群聊中|否（默认开启）|勾选或取消勾选| - -### 群类型说明 -创建群聊节点支持以下群类型： -|类型ID|类型名称|说明| +|Nome Gruppo|Impostare il nome della chat di gruppo da creare|Sì|"Gruppo Sviluppo Progetto A"| +|Proprietario Gruppo|Impostare l'amministratore della chat di gruppo, deve essere specificato un utente come proprietario|Sì|Variabile utente o selezione diretta| +|Membri Gruppo|Lista di altri membri da aggiungere alla chat di gruppo|No|Array utenti o selezione diretta| +|Tipo Gruppo|Selezionare il tipo di chat di gruppo, diversi tipi possono avere impostazioni di permessi diverse|Sì|Gruppo interno, gruppo progetto, ecc.| +|Aggiungere Utente Corrente al Gruppo|Se aggiungere l'utente che ha attivato il flusso di lavoro alla chat di gruppo|No (attivato di default)|Selezionare o deselezionare| +|Aggiungere Assistente Corrente al Gruppo|Se aggiungere l'AI assistente del flusso di lavoro corrente alla chat di gruppo|No (attivato di default)|Selezionare o deselezionare| + +### Spiegazione Tipi di Gruppo + +Il Nodo Creazione Chat di Gruppo supporta i seguenti tipi di gruppo: +|ID Tipo|Nome Tipo|Spiegazione| |---|---|---| -|1|内部群|组织内部的普通群聊| -|2|内部培训群|用于内部培训的专用群聊| -|3|内部会议群|用于内部会议讨论的群聊| -|4|内部项目群|用于项目协作的群聊| -|5|内部工单群|用于工单处理的群聊| -|6|外部群|可包含外部成员的群聊| - -### 输出结果 -创建群聊节点没有标准的输出参数，它的主要作用是执行创建的群聊动作。 -## 使用说明 -### 基本配置步骤 -1. **添加节点**：在工作流编辑器中，从左侧节点面板选择"创建群聊"节点，拖拽到工作流画布中适当位置。 -2. **设置群名称**： - 1. 点击"群名称"输入框 - 2. 输入一个有意义的群聊名称，或者选择一个包含群名的变量 -3. **选择群主**： - 1. 点击"群主"选择框 - 2. 从用户列表中选择一位用户作为群主，或者使用变量引用 -4. **添加群成员**（可选）： - 1. 点击"群成员"选择框 - 2. 选择需要添加的群成员，可以是多个用户或用户数组变量 -5. **选择群类型**： - 1. 从下拉菜单中选择适合您需求的群类型 -6. **设置自动添加选项**： - 1. 根据需要，选择是否自动将当前用户和助理添加进群聊 -### 进阶技巧 -1. **动态设置群名称**： - 1. 可以使用变量组合生成群名称，如：`"项目项目名称讨论群"` - 2. 这样可以根据实际业务数据自动生成有意义的群名称 -2. **智能群成员添加**： - 1. 结合"人员检索"节点，可以根据部门、职位或标签自动查找并添加相关人员 - 2. 例如：`部门.技术部.成员`将添加技术部全体成员 -3. **条件性创建群聊**： - 1. 搭配"条件分支"节点，可以根据不同条件创建不同类型的群聊 - 2. 比如根据项目规模大小，创建不同类型的项目群 -4. **群聊创建后的自动操作**： - 1. 可以在创建群聊后，使用"消息回复"节点自动在群内发送欢迎消息 - 2. 也可以使用"大模型调用"节点生成个性化的群公告 -## 注意事项 -### 群主设置 -- 群主必须是系统中的有效用户，否则群聊创建将失败 -- 如使用变量设置群主，请确保变量值为有效的用户对象，包含用户ID信息 -- 推荐使用"人员检索"节点的结果作为群主和群成员输入 -### 群成员限制 -- 添加过多成员可能会影响群聊创建性能，建议控制在合理范围内 -- 如果某些用户不存在或无法添加，节点会跳过这些无效用户，不会导致整个节点失败 -### 助理开场白 -- 只有当"将当前助理添加进群聊"选项开启时，助理开场白设置才会生效 -- 助理开场白支持变量引用，可以根据业务上下文动态生成个性化开场白 -### 群聊创建条件 -- 创建群聊功能仅在IM聊天环境中有效 -- 在非IM环境（如API调用、定时触发等）中，节点会模拟创建过程但不会实际创建群聊 -## 常见问题 -### 创建群聊失败怎么办？ -**问题**： -配置了创建群聊节点，但执行时报错或未能成功创建群聊。 - -**解决方案**： -1. 检查群主是否为有效用户，群主必须是系统中已存在的用户 -2. 确认群名称不为空且格式正确 -3. 验证选择的群类型是否有效 -4. 检查执行环境是否支持创建群聊（需在IM环境中） -### 如何获取创建的群聊ID？ - -**问题**： -创建群聊后，如何在后续节点中引用这个群聊？ - -**解决方案**： -创建群聊节点会输出包含群ID的结果，可以在后续节点中通过变量引用获取： -- 使用 `上一节点.result.group_id` 获取群聊ID -- 使用 `上一节点.result.name` 获取群聊名称 -### 为什么有些用户无法被添加到群聊？ - -**问题**： -配置了多个群成员，但有些成员没有被成功添加到群聊中。 - -**解决方案**： -1. 确认这些用户在系统中存在且状态正常 -2. 检查是否因为权限问题导致无法添加某些用户 -3. 验证用户数据格式是否正确，必须包含用户ID信息 -## 常见搭配节点 -|**节点类型**|**搭配原因**| +|1|Gruppo Interno|Chat di gruppo ordinaria interna all'organizzazione| +|2|Gruppo Formazione Interno|Chat di gruppo dedicata per formazione interna| +|3|Gruppo Riunione Interno|Chat di gruppo per discussioni di riunioni interne| +|4|Gruppo Progetto Interno|Chat di gruppo per collaborazione di progetto| +|5|Gruppo Ticket Interno|Chat di gruppo per elaborazione ticket| +|6|Gruppo Esterno|Chat di gruppo che può includere membri esterni| + +### Risultati di Output + +Il Nodo Creazione Chat di Gruppo non ha parametri di output standard, la sua funzione principale è eseguire l'azione di creazione della chat di gruppo. + +## Istruzioni per l'Uso + +### Passi di Configurazione Base + +1. **Aggiungere Nodo**: Nell'editor del flusso di lavoro, selezionare il nodo "Creazione Chat di Gruppo" dal pannello dei nodi a sinistra, trascinarlo nella posizione appropriata sulla tela del flusso di lavoro. +2. **Impostare Nome Gruppo**: + 1. Cliccare sulla casella di input "Nome Gruppo" + 2. Inserire un nome significativo per la chat di gruppo, o selezionare una variabile che contiene il nome del gruppo +3. **Selezionare Proprietario Gruppo**: + 1. Cliccare sulla casella di selezione "Proprietario Gruppo" + 2. Selezionare un utente dalla lista utenti come proprietario del gruppo, o utilizzare un riferimento a variabile +4. **Aggiungere Membri del Gruppo** (opzionale): + 1. Cliccare sulla casella di selezione "Membri Gruppo" + 2. Selezionare i membri del gruppo da aggiungere, possono essere molteplici utenti o variabili array di utenti +5. **Selezionare Tipo di Gruppo**: + 1. Selezionare dal menu a tendina il tipo di gruppo adatto alle proprie esigenze +6. **Impostare Opzioni di Aggiunta Automatica**: + 1. Secondo le necessità, scegliere se aggiungere automaticamente l'utente corrente e l'assistente alla chat di gruppo + +### Tecniche Avanzate + +1. **Impostazione Dinamica Nome Gruppo**: + 1. È possibile utilizzare combinazioni di variabili per generare il nome del gruppo, come: `"Gruppo Discussione Progetto {nome_progetto}"` + 2. In questo modo è possibile generare automaticamente nomi di gruppo significativi secondo i dati aziendali effettivi +2. **Aggiunta Intelligente Membri del Gruppo**: + 1. Combinando il nodo "Ricerca Personale", è possibile cercare e aggiungere automaticamente personale correlato secondo dipartimento, posizione o etichette + 2. Ad esempio: `dipartimento.tecnologia.membri` aggiungerà tutti i membri del dipartimento tecnologia +3. **Creazione Condizionale Chat di Gruppo**: + 1. Abbinando il nodo "Diramazione Condizionale", è possibile creare diversi tipi di chat di gruppo secondo diverse condizioni + 2. Ad esempio, secondo la dimensione del progetto, creare diversi tipi di gruppi progetto +4. **Operazioni Automatiche dopo Creazione Gruppo**: + 1. Dopo la creazione della chat di gruppo, è possibile utilizzare il nodo "Risposta Messaggio" per inviare automaticamente messaggi di benvenuto nel gruppo + 2. È anche possibile utilizzare il nodo "Chiamata Modello Grande" per generare annunci di gruppo personalizzati + +## Note Importanti + +### Impostazione Proprietario Gruppo + +- Il proprietario del gruppo deve essere un utente valido nel sistema, altrimenti la creazione della chat di gruppo fallirà +- Se si utilizza una variabile per impostare il proprietario del gruppo, assicurarsi che il valore della variabile sia un oggetto utente valido, contenente informazioni ID utente +- Si raccomanda di utilizzare i risultati del nodo "Ricerca Personale" come input per proprietario del gruppo e membri del gruppo + +### Limitazioni Membri del Gruppo + +- Aggiungere troppi membri potrebbe influenzare le prestazioni di creazione della chat di gruppo, si consiglia di mantenerlo in un range ragionevole +- Se alcuni utenti non esistono o non possono essere aggiunti, il nodo salterà questi utenti non validi, senza causare il fallimento dell'intero nodo + +### Messaggio di Presentazione Assistente + +- L'impostazione del messaggio di presentazione dell'assistente avrà effetto solo quando l'opzione "Aggiungere Assistente Corrente al Gruppo" è attivata +- Il messaggio di presentazione dell'assistente supporta riferimenti a variabili, può generare dinamicamente messaggi di presentazione personalizzati secondo il contesto aziendale + +### Condizioni di Creazione Chat di Gruppo + +- La funzionalità di creazione chat di gruppo è valida solo nell'ambiente di chat IM +- In ambienti non IM (come chiamate API, attivazioni programmate, ecc.), il nodo simulerà il processo di creazione ma non creerà effettivamente la chat di gruppo + +## Domande Frequenti + +### Cosa fare se la creazione della chat di gruppo fallisce? + +**Problema**: +È stato configurato il nodo di creazione chat di gruppo, ma durante l'esecuzione si verifica un errore o non riesce a creare con successo la chat di gruppo. + +**Soluzioni**: +1. Verificare che il proprietario del gruppo sia un utente valido, il proprietario deve essere un utente già esistente nel sistema +2. Confermare che il nome del gruppo non sia vuoto e che il formato sia corretto +3. Verificare che il tipo di gruppo selezionato sia valido +4. Controllare se l'ambiente di esecuzione supporti la creazione di chat di gruppo (deve essere in ambiente IM) + +### Come ottenere l'ID della chat di gruppo creata? + +**Problema**: +Dopo aver creato la chat di gruppo, come referenziare questa chat di gruppo nei nodi successivi? + +**Soluzioni**: +Il nodo di creazione chat di gruppo restituirà risultati contenenti l'ID del gruppo, che possono essere ottenuti nei nodi successivi attraverso riferimenti a variabili: +- Utilizzare `nodo_precedente.result.group_id` per ottenere l'ID della chat di gruppo +- Utilizzare `nodo_precedente.result.name` per ottenere il nome della chat di gruppo + +### Perché alcuni utenti non possono essere aggiunti alla chat di gruppo? + +**Problema**: +Sono stati configurati molteplici membri del gruppo, ma alcuni membri non sono stati aggiunti con successo alla chat di gruppo. + +**Soluzioni**: +1. Confermare che questi utenti esistano nel sistema e che il loro stato sia normale +2. Verificare se problemi di permessi impediscano l'aggiunta di alcuni utenti +3. Validare che il formato dei dati utente sia corretto, deve contenere informazioni ID utente + +## Nodi di Combinazione Comuni + +|Tipo Nodo|Motivo Combinazione| |---|---| -|人员检索节点|检索符合条件的用户，将这些用户作为群成员创建群聊| -|条件分支节点|根据不同条件创建不同类型或不同成员组成的群聊| -|大模型调用节点|使用大模型生成个性化的群名称或开场白| \ No newline at end of file +|Nodo Ricerca Personale|Cercare utenti che soddisfano le condizioni, utilizzare questi utenti come membri del gruppo per creare la chat di gruppo| +|Nodo Diramazione Condizionale|Secondo diverse condizioni creare diversi tipi o gruppi con diverse composizioni di membri| +|Nodo Chiamata Modello Grande|Utilizzare il modello grande per generare nomi di gruppo personalizzati o messaggi di presentazione| \ No newline at end of file diff --git a/docs/zh/tutorial/basic/node/Data-loading.md b/docs/zh/tutorial/basic/node/Data-loading.md index f8f6d2b03..d5a12e021 100644 --- a/docs/zh/tutorial/basic/node/Data-loading.md +++ b/docs/zh/tutorial/basic/node/Data-loading.md @@ -1,75 +1,104 @@ -# 数据加载节点 -## 什么是数据加载节点？ -数据加载节点是一个用于从持久化数据库中读取之前存储的数据的工具。它就像是一个智能检索员，能够根据您提供的"数据键"，快速找到并取出之前保存在持久化数据库中的信息，供工作流中的其他节点使用。 - -**图片说明：** - -数据加载节点界面主要由查询条件区域组成，包括作用域选择、数据键输入框等关键元素。用户可以通过配置这些参数从持久化数据库中检索出之前存储的数据。 -![数据加载节点](https://cdn.letsmagic.cn/static/img/Data-loading.png) - -## 为什么需要数据加载节点？ -**在智能工作流中，常常需要在不同时间或不同会话之间传递和使用数据。例如：** -- 记住用户的偏好设置，下次对话时直接使用 -- 存储上次交互的关键信息，以便后续处理 -- 保存业务数据，允许在未来任何时候检索使用 -数据加载节点正是为解决这一需求而设计的，它让您可以方便地检索出之前存储的任何信息，建立起工作流的"长期记忆"能力，使AI 助理拥有持久化的数据访问能力。 -## 适用场景 -数据加载节点适用于以下场景： -1. **用户设置记忆**：读取用户的偏好设置、使用习惯等信息，提供个性化服务 -2. **业务流程连续性**：在多次对话之间保持业务连续性，如读取上次未完成的订单信息 -3. **知识检索**：从持久化存储中读取之前保存的专业知识或规则 -4. **用户身份识别**：读取用户的身份信息，用于后续的权限控制和个性化服务 -## 节点参数说明 -### 输入参数 -|参数名称|参数描述|是否必填|默认值|说明| +# Nodo Caricamento Dati 📊 + +## Che cos'è il Nodo Caricamento Dati? + +Il Nodo Caricamento Dati è uno strumento utilizzato per leggere dati precedentemente memorizzati da un database persistente. È come un intelligente ricercatore che, secondo la "chiave dati" fornita dall'utente, può rapidamente trovare e estrarre le informazioni precedentemente salvate nel database persistente, per l'utilizzo da parte di altri nodi nel flusso di lavoro. + +**Spiegazione Immagine:** + +L'interfaccia del Nodo Caricamento Dati è composta principalmente dall'area delle condizioni di query, inclusi elementi chiave come la selezione dell'ambito, la casella di input della chiave dati, ecc. Gli utenti possono recuperare dati precedentemente memorizzati nel database persistente configurando questi parametri. +![Nodo Caricamento Dati](https://cdn.letsmagic.cn/static/img/Data-loading.png) + +## Perché serve il Nodo Caricamento Dati? + +**Nei flussi di lavoro intelligenti, spesso è necessario trasferire e utilizzare dati tra diversi momenti o diverse sessioni. Ad esempio:** +- Ricordare le preferenze dell'utente, utilizzarle direttamente nella prossima conversazione +- Memorizzare informazioni chiave dell'ultima interazione, per l'elaborazione successiva +- Salvare dati aziendali, permettendo il recupero in qualsiasi momento futuro + +Il Nodo Caricamento Dati è progettato proprio per soddisfare questa esigenza, permette di recuperare convenientemente qualsiasi informazione precedentemente memorizzata, stabilendo la capacità di "memoria a lungo termine" del flusso di lavoro, facendo sì che l'assistente AI abbia capacità di accesso ai dati persistenti. + +## Scenari di Applicazione + +Il Nodo Caricamento Dati è applicabile nei seguenti scenari: +1. **Memoria Impostazioni Utente**: Leggere informazioni sulle preferenze dell'utente, abitudini d'uso, ecc., fornire servizi personalizzati +2. **Continuità Processo Aziendale**: Mantenere la continuità aziendale tra molteplici conversazioni, come leggere informazioni di ordini incompleti dalla volta precedente +3. **Ricerca Conoscenza**: Leggere conoscenze professionali o regole precedentemente salvate dal deposito persistente +4. **Identificazione Identità Utente**: Leggere informazioni di identità dell'utente, per il controllo dei permessi successivo e servizi personalizzati + +## Spiegazione Parametri del Nodo + +### Parametri di Input + +|Nome Parametro|Descrizione Parametro|Obbligatorio|Valore Default|Spiegazione| |---|---|---|---|---| -|作用域|数据的存储范围|是|当前话题|确定从哪个范围内查找数据，可选范围包括：当前话题、全局等| -|数据键|要读取的数据的标识符|是|无|用于查找数据的唯一标识，支持使用变量，如"@用户ID"| +|Ambito|D'ambito di memorizzazione dei dati|Sì|Argomento Corrente|Determina da quale ambito cercare i dati, gli ambiti opzionali includono: argomento corrente, globale, ecc.| +|Chiave Dati|L'identificatore dei dati da leggere|Sì|Nessuno|Utilizzato per cercare l'identificatore unico dei dati, supporta l'utilizzo di variabili, come "@ID_Utente"| + +### Parametri di Output -### 输出参数 -数据加载节点成功执行后，会输出以下变量，可在后续节点中使用： -|输出变量名|数据类型|说明| +Dopo l'esecuzione riuscita del Nodo Caricamento Dati, verranno emesse le seguenti variabili, utilizzabili nei nodi successivi: +|Nome Variabile Output|Tipo Dati|Spiegazione| |---|---|---| -|数据值（value）|字符串/数组|根据存储时的数据类型，可能是简单的文本字符串，也可能是复杂的JSON对象或数组| - -## 使用说明 -### 基本配置步骤 -1. **选择作用域**：从下拉菜单中选择要查询的数据作用域，通常有"当前话题"、"当前用户"等选项 -2. **设置数据键**：在"数据键"输入框中输入要读取的数据的标识符 - 1. 可以直接输入文本，如"用户偏好" - 2. 也可以点击"@"按钮，从变量列表中选择一个变量作为数据键 -3. **连接后续节点**：将数据加载节点的输出连接到需要使用该数据的后续节点 -### 进阶技巧 -1. **动态数据键**：当您需要根据不同情况读取不同的数据时，可以使用变量作为数据键。例如，您可以使用"@用户ID"作为数据键，系统会根据当前用户ID自动读取对应的数据。 -2. **结合条件判断**：在读取数据后，可以使用条件判断节点检查数据是否存在、是否有效，从而构建更复杂的逻辑流程。 -3. **数据转换**：如果读取的是JSON格式数据，可以使用代码节点进行解析和转换，提取其中的特定字段。 -## 注意事项 -### 数据不存在的处理 -当要读取的数据键在数据库中不存在时，数据加载节点会输出一个空值。在后续节点中，建议先判断该值是否为空，避免因数据不存在导致流程出错。 -### 数据过期问题 -如果数据在存储时设置了过期时间，超过该时间后数据会自动失效。请确保在数据可能过期的情况下有适当的备选处理方案。 -### 数据类型一致性 -数据加载节点会返回与存储时相同类型的数据。例如，如果存储的是JSON对象，加载时也会获得JSON对象。请确保后续节点能正确处理该类型的数据。 -## 常见问题 -### 问题1：为什么我读取不到之前存储的数据？ -**可能原因**： -- 数据键名称错误或拼写不一致 -- 作用域选择错误（例如数据存储在"全局"作用域，但读取时选择了"当前话题"） -- 数据已过期（如果存储时设置了过期时间） -- 数据可能被其他流程删除或覆盖 -**解决方法**： -- 确认数据键的名称是否与存储时完全一致 -- 检查作用域是否与存储时相同 -- 如果怀疑数据已过期，可以先重新存储一次 -- 在数据加载节点后添加日志或调试节点，输出加载的结果进行检查 -### 问题2：如何判断数据是否成功加载？ -**解决方法**： - -在数据加载节点后添加条件判断节点，检查输出的 value 是否为空。如果不为空，则说明成功加载了数据；如果为空，则可能是数据不存在或已过期。 -## 常见搭配节点 -|**节点类型**|**搭配原因**| +|Valore Dati (value)|Stringa/Array|Secondo il tipo di dati al momento della memorizzazione, potrebbe essere una semplice stringa di testo, oppure un oggetto JSON complesso o array| + +## Istruzioni per l'Uso + +### Passi di Configurazione Base + +1. **Selezionare Ambito**: Dal menu a tendina selezionare l'ambito dei dati da interrogare, solitamente ci sono opzioni come "Argomento Corrente", "Utente Corrente", ecc. +2. **Impostare Chiave Dati**: Nella casella di input "Chiave Dati" inserire l'identificatore dei dati da leggere + 1. È possibile inserire direttamente testo, come "Preferenze Utente" + 2. È anche possibile cliccare il pulsante "@" per selezionare una variabile dalla lista delle variabili come chiave dati +3. **Connettere Nodi Successivi**: Connettere l'output del nodo caricamento dati ai nodi successivi che necessitano di utilizzare questi dati + +### Tecniche Avanzate + +1. **Chiave Dati Dinamica**: Quando è necessario leggere dati diversi secondo diverse situazioni, è possibile utilizzare variabili come chiave dati. Ad esempio, è possibile utilizzare "@ID_Utente" come chiave dati, il sistema leggerà automaticamente i dati corrispondenti secondo l'ID utente corrente. +2. **Combinazione con Giudizio Condizionale**: Dopo aver letto i dati, è possibile utilizzare il nodo di giudizio condizionale per verificare se i dati esistono, se sono validi, costruendo così processi logici più complessi. +3. **Conversione Dati**: Se i dati letti sono in formato JSON, è possibile utilizzare il nodo codice per analizzarli e convertirli, estraendo campi specifici. + +## Note Importanti + +### Gestione Dati Inesistenti + +Quando la chiave dati da leggere non esiste nel database, il Nodo Caricamento Dati emetterà un valore vuoto. Nei nodi successivi, si consiglia di verificare prima se questo valore è vuoto, per evitare che il processo vada in errore a causa di dati inesistenti. + +### Problema Scadenza Dati + +Se i dati hanno un tempo di scadenza impostato al momento della memorizzazione, dopo tale tempo i dati diventeranno automaticamente invalidi. Assicurarsi di avere schemi di elaborazione alternativi appropriati nel caso in cui i dati possano scadere. + +### Consistenza Tipo Dati + +Il Nodo Caricamento Dati restituirà dati dello stesso tipo di quando sono stati memorizzati. Ad esempio, se è stato memorizzato un oggetto JSON, al momento del caricamento si otterrà anche un oggetto JSON. Assicurarsi che i nodi successivi possano elaborare correttamente questo tipo di dati. + +## Domande Frequenti + +### Problema 1: Perché non riesco a leggere i dati precedentemente memorizzati? + +**Possibili Cause**: +- Nome chiave dati errato o errori di ortografia +- Selezione ambito errata (ad esempio i dati sono memorizzati nell'ambito "Globale", ma durante la lettura è stato selezionato "Argomento Corrente") +- I dati sono scaduti (se al momento della memorizzazione è stato impostato un tempo di scadenza) +- I dati potrebbero essere stati eliminati o sovrascritti da altri processi + +**Metodi di Risoluzione**: +- Confermare che il nome della chiave dati sia completamente identico a quello della memorizzazione +- Verificare che l'ambito sia lo stesso della memorizzazione +- Se si sospetta che i dati siano scaduti, è possibile memorizzarli nuovamente prima +- Dopo il nodo caricamento dati aggiungere nodi di log o debug, emettere i risultati del caricamento per verificarli + +### Problema 2: Come giudicare se i dati sono stati caricati con successo? + +**Metodo di Risoluzione**: + +Dopo il nodo caricamento dati aggiungere un nodo di giudizio condizionale, verificare se il valore di output value sia vuoto. Se non è vuoto, significa che i dati sono stati caricati con successo; se è vuoto, potrebbe significare che i dati non esistono o sono scaduti. + +## Nodi di Combinazione Comuni + +|Tipo Nodo|Motivo Combinazione| |---|---| -|条件判断节点|读取数据后进行判断，决定后续流程| -|代码执行节点|对读取的复杂数据进行处理和转换| -|大模型调用节点|将读取的数据作为上下文传递给大模型，提升模型回答的相关性| -|数据存储节点|先使用数据存储节点保存数据，后续使用数据加载节点读取| \ No newline at end of file +|Nodo Giudizio Condizionale|Dopo aver letto i dati effettuare giudizi, decidere il processo successivo| +|Nodo Esecuzione Codice|Elaborare e convertire dati complessi letti| +|Nodo Chiamata Modello Grande|Passare i dati letti come contesto al modello grande, migliorare la pertinenza delle risposte del modello| +|Nodo Memorizzazione Dati|Utilizzare prima il nodo memorizzazione dati per salvare i dati, successivamente utilizzare il nodo caricamento dati per leggerli| \ No newline at end of file diff --git a/docs/zh/tutorial/basic/node/Data-storage.md b/docs/zh/tutorial/basic/node/Data-storage.md index cc7f711c6..6642f7872 100644 --- a/docs/zh/tutorial/basic/node/Data-storage.md +++ b/docs/zh/tutorial/basic/node/Data-storage.md @@ -1,80 +1,109 @@ -# 数据存储节点 -## 什么是数据存储节点？ -数据存储节点是麦吉平台中用于将关键信息持久化保存的功能组件。它就像一个可靠的笔记本，能够记录下工作流中的重要数据，并在需要时随时查阅使用，即使在对话结束后依然保留这些信息。 - -**图片说明：** - -数据存储节点界面主要包含作用域选择区、数据键输入区、数据值编辑区和过期时间设置区四个主要部分，通过这些区域的配置，用户可以指定要保存的数据及其存储方式。 -![数据存储节点](https://cdn.letsmagic.cn/static/img/Data-storage.png) - -## 为什么需要数据存储节点？ -在AI 助理使用过程中，我们经常需要记住一些重要信息以便后续使用，例如： -1. **跨会话记忆**：用户的偏好设置、历史互动记录等需要长期保存 -2. **数据持久化**：将临时生成的重要数据（如分析结果、用户输入的关键信息）保存起来 -3. **状态管理**：记录工作流的执行状态，支持复杂业务流程的断点续传 -4. **共享信息**：在不同的AI 助理或工作流之间共享数据 -数据存储节点就像是AI 助理的"长期记忆"，让AI 助理具备了"过目不忘"的能力，极大提升了用户体验和AI 助理的实用性。 -## 适用场景 -### 场景一：用户信息记忆 -记住用户的姓名、偏好等个人信息，在后续交互中直接调用，无需重复询问，提供个性化服务。 -### 场景二：多轮对话上下文保存 -在复杂问题解决过程中，保存中间结果或讨论要点，即使对话中断后重新开始，也能快速回到之前的讨论状态。 -### 场景三：业务状态跟踪 -在办理业务流程中，记录用户当前处理到哪一步，以便下次继续办理时无需重头开始。 -## 节点参数说明 -### 输入说明 -|参数名称|说明|是否必填| +# Nodo Memorizzazione Dati 💾 + +## Che cos'è il Nodo Memorizzazione Dati? + +Il Nodo Memorizzazione Dati è un componente funzionale nella piattaforma Magic utilizzato per salvare in modo persistente informazioni chiave. È come un affidabile blocco note che può registrare importanti dati nel flusso di lavoro e consultarli in qualsiasi momento necessario, mantenendo queste informazioni anche dopo la fine della conversazione. + +**Spiegazione Immagine:** + +L'interfaccia del Nodo Memorizzazione Dati contiene principalmente quattro parti principali: area di selezione dell'ambito, area di input della chiave dati, area di modifica del valore dati e area di impostazione del tempo di scadenza. Attraverso la configurazione di queste aree, gli utenti possono specificare i dati da salvare e il loro metodo di memorizzazione. +![Nodo Memorizzazione Dati](https://cdn.letsmagic.cn/static/img/Data-storage.png) + +## Perché serve il Nodo Memorizzazione Dati? + +Durante l'utilizzo dell'assistente AI, spesso abbiamo bisogno di ricordare alcune informazioni importanti per utilizzi successivi, ad esempio: +1. **Memoria tra Sessioni**: Preferenze utente, registri di interazioni storiche, ecc. che necessitano di essere salvati a lungo termine +2. **Persistenza Dati**: Salvare dati importanti generati temporaneamente (come risultati di analisi, informazioni chiave inserite dall'utente) +3. **Gestione Stato**: Registrare lo stato di esecuzione del flusso di lavoro, supportare la continuazione da punto di interruzione per processi aziendali complessi +4. **Condivisione Informazioni**: Condividere dati tra diversi assistenti AI o flussi di lavoro + +Il Nodo Memorizzazione Dati è come la "memoria a lungo termine" dell'assistente AI, permette all'assistente AI di avere la capacità di "non dimenticare mai ciò che ha visto", migliorando enormemente l'esperienza utente e l'utilità dell'assistente AI. + +## Scenari di Applicazione + +### Scenario 1: Memoria Informazioni Utente +Ricordare nome utente, preferenze, ecc., richiamarli direttamente nelle interazioni successive, senza bisogno di chiedere ripetutamente, fornendo servizi personalizzati. + +### Scenario 2: Salvataggio Contesto Conversazione Multi-turno +Nel processo di risoluzione di problemi complessi, salvare risultati intermedi o punti chiave della discussione, in modo che anche se la conversazione viene interrotta e ripresa, si possa tornare rapidamente allo stato di discussione precedente. + +### Scenario 3: Tracciamento Stato Aziendale +Nel processo di gestione di pratiche aziendali, registrare a quale passo è arrivato l'utente attualmente, in modo che al prossimo proseguimento della pratica non sia necessario ricominciare da capo. + +## Spiegazione Parametri del Nodo + +### Spiegazione Input + +|Nome Parametro|Spiegazione|Obbligatorio| |---|---|---| -|作用域|选择数据的存储范围，决定谁可以访问这些数据。默认选项通常是"当前话题"。|是| -|数据键|用于标识存储的数据，相当于数据的"名字"，便于后续查找和使用。支持使用"@"引用变量。|是| -|数据值|需要存储的具体内容，可以是文本、数字或其他格式的数据。支持使用"@"引用变量。|是| -|过期时间（秒）|设置数据的有效期，超过该时间后数据将被自动删除。不填则表示永不过期。支持使用"@"引用变量。|否| - -### 输出说明 -数据存储节点会将指定的数据保存到持久化存储中，但不直接生成输出变量。保存成功后，可通过"数据加载节点"使用相同的键名来检索已保存的数据。 -## 使用说明 -### 基本配置步骤 -1. **添加数据存储节点**：在工作流编辑器中，将数据存储节点拖入画布。 -2. **配置作用域**：选择适合的作用域，通常使用"当前话题"即可满足大多数需求。 -3. **设置数据键**：为要存储的数据指定一个清晰、有意义的名称，便于日后识别。 - 1. 例如：`user_preference`、`last_order_id`等。 - 2. 如需使用变量作为键名，可点击"@"按钮选择现有变量。 -4. **填写数据值**：输入需要存储的具体内容。 - 1. 可以是固定文本，如`"已完成订单"`。 - 2. 也可以引用变量，如`@user_response`。 -5. **设置过期时间**（可选）：根据数据的使用场景设置合适的过期时间。 - 1. 临时数据可设置较短时间，如`3600`（1小时）。 - 2. 长期使用的数据可留空（永不过期）或设置较长时间。 -### 进阶技巧 -1. **动态键名设计**： - 1. 可以使用变量组合生成动态键名，如`user_@user_id`，这样可以为不同用户创建专属的数据条目。 - 2. 使用有规律的键名前缀，如`temp_data_1`、`temp_data_2`，便于批量管理相关数据。 -2. **数据组织优化**： - 1. 对于复杂数据，可以考虑使用JSON格式存储，如`{"name": "张三", "age": 28}`。 - 2. 使用前缀区分不同业务数据，如`order_xxx`和`user_xxx`。 -## 注意事项 -### 数据键命名规范 -1. **避免特殊字符**：键名应尽量使用字母、数字和下划线，避免特殊字符可能引起的解析问题。 -2. **保持唯一性**：在相同作用域内，不同数据应使用不同的键名，否则新值会覆盖旧值。 -3. **命名有意义**：使用能反映数据内容的键名，提高代码可读性，如`user_age`比`u_a`更直观。 -### 数据存储限制 -1. **数据大小限制**：单个数据项大小应控制在合理范围内（通常建议不超过10MB）。 -2. **存储容量考虑**：持久化存储有总容量限制，请合理规划使用，及时清理不需要的数据。 -3. **敏感信息处理**：避免存储用户隐私等敏感信息，如必须存储，请确保加密处理。 -## 常见问题 -### 保存的数据找不到了怎么办？ -**回答**：可能的原因有： -- 数据键名拼写错误：检查数据加载时使用的键名是否与存储时完全一致。 -- 作用域选择不同：确保加载数据时选择了与存储时相同的作用域。 -- 数据已过期：检查存储时设置的过期时间是否已到。 -- 数据被其他流程覆盖：同名键会被新值覆盖，检查是否有其他流程使用了相同的键名。 -### 如何高效管理多个相关数据？ -**回答**：推荐以下方法： -- 使用命名前缀：如所有与用户相关的数据键以"user_"开头。 -- 采用JSON格式：将相关数据组织成JSON对象一起存储，而不是分散存储。 -- 设置合理的过期时间：临时数据设置较短的过期时间，自动清理不再需要的数据。 -## 常见搭配节点 -|**节点类型**|**搭配原因**| +|Ambito|Selezionare l'ambito di memorizzazione dei dati, determinare chi può accedere a questi dati. L'opzione predefinita solitamente è "Argomento Corrente".|Sì| +|Chiave Dati|Utilizzata per identificare i dati memorizzati, equivalente al "nome" dei dati, facilitando la ricerca e l'utilizzo successivi. Supporta l'utilizzo di "@" per referenziare variabili.|Sì| +|Valore Dati|Il contenuto specifico da memorizzare, può essere testo, numeri o dati in altri formati. Supporta l'utilizzo di "@" per referenziare variabili.|Sì| +|Tempo Scadenza (secondi)|Impostare il periodo di validità dei dati, dopo tale tempo i dati verranno automaticamente eliminati. Se non compilato significa che non scade mai. Supporta l'utilizzo di "@" per referenziare variabili.|No| + +### Spiegazione Output + +Il Nodo Memorizzazione Dati salverà i dati specificati nel deposito persistente, ma non genera direttamente variabili di output. Dopo il salvataggio riuscito, è possibile utilizzare il "Nodo Caricamento Dati" con lo stesso nome chiave per recuperare i dati salvati. + +## Istruzioni per l'Uso + +### Passi di Configurazione Base + +1. **Aggiungere Nodo Memorizzazione Dati**: Nell'editor del flusso di lavoro, trascinare il nodo memorizzazione dati nella tela. +2. **Configurare Ambito**: Selezionare l'ambito appropriato, solitamente utilizzare "Argomento Corrente" può soddisfare la maggior parte delle esigenze. +3. **Impostare Chiave Dati**: Specificare un nome chiaro e significativo per i dati da memorizzare, per facilitare l'identificazione futura. + 1. Ad esempio: `user_preference`, `last_order_id`, ecc. + 2. Se necessario utilizzare variabile come nome chiave, cliccare il pulsante "@" per selezionare variabili esistenti. +4. **Compilare Valore Dati**: Inserire il contenuto specifico da memorizzare. + 1. Può essere testo fisso, come `"Ordine Completato"`. + 2. Può anche referenziare variabile, come `@user_response`. +5. **Impostare Tempo Scadenza** (opzionale): Secondo lo scenario di utilizzo dei dati impostare un tempo di scadenza appropriato. + 1. Dati temporanei possono impostare tempo breve, come `3600` (1 ora). + 2. Dati per utilizzo a lungo termine possono lasciare vuoto (mai scadenza) o impostare tempo lungo. + +### Tecniche Avanzate + +1. **Progettazione Nome Chiave Dinamica**: + 1. È possibile utilizzare combinazioni di variabili per generare nomi chiave dinamici, come `user_@user_id`, in questo modo è possibile creare voci dati dedicate per diversi utenti. + 2. Utilizzare prefissi nome con regolarità, come `temp_data_1`, `temp_data_2`, facilitando la gestione in batch di dati correlati. +2. **Ottimizzazione Organizzazione Dati**: + 1. Per dati complessi, considerare l'utilizzo del formato JSON per la memorizzazione, come `{"name": "Mario", "age": 28}`. + 2. Utilizzare prefissi per distinguere dati aziendali diversi, come `order_xxx` e `user_xxx`. + +## Note Importanti + +### Norme Denominazione Chiave Dati + +1. **Evitare Caratteri Speciali**: Il nome chiave dovrebbe utilizzare principalmente lettere, numeri e trattini bassi, evitare caratteri speciali che potrebbero causare problemi di analisi. +2. **Mantenere Unicità**: Nello stesso ambito, dati diversi dovrebbero utilizzare nomi chiave diversi, altrimenti il nuovo valore sovrascriverà il vecchio. +3. **Denominazione Significativa**: Utilizzare nomi chiave che possano riflettere il contenuto dei dati, migliorare la leggibilità del codice, come `user_age` è più intuitivo di `u_a`. + +### Limitazioni Memorizzazione Dati + +1. **Limitazione Dimensione Dati**: La dimensione di ogni singolo elemento dati dovrebbe essere controllata in un range ragionevole (solitamente suggerito non superare 10MB). +2. **Considerazione Capacità Deposito**: Il deposito persistente ha una limitazione di capacità totale, pianificare ragionevolmente l'utilizzo, pulire tempestivamente i dati non necessari. +3. **Gestione Informazioni Sensibili**: Evitare di memorizzare informazioni sensibili come privacy utente, se necessario memorizzare, assicurarsi di crittografarle. + +## Domande Frequenti + +### Cosa fare se i dati salvati non si trovano? + +**Risposta**: Le possibili cause sono: +- Errore ortografia nome chiave: Verificare se il nome chiave utilizzato nel caricamento dati sia completamente identico a quello della memorizzazione. +- Selezione ambito diverso: Assicurarsi che nell'ambito di caricamento dati sia selezionato lo stesso di quello di memorizzazione. +- Dati scaduti: Verificare se il tempo di scadenza impostato nella memorizzazione sia già trascorso. +- Dati sovrascritti da altri processi: Chiavi con lo stesso nome verranno sovrascritte dai nuovi valori, verificare se altri processi abbiano utilizzato lo stesso nome chiave. + +### Come gestire efficientemente molteplici dati correlati? + +**Risposta**: Si raccomandano i seguenti metodi: +- Utilizzare prefissi nome: Come tutti i dati correlati all'utente iniziano con "user_". +- Adottare formato JSON: Organizzare dati correlati in oggetti JSON da memorizzare insieme, piuttosto che memorizzarli in modo disperso. +- Impostare tempo di scadenza ragionevole: Dati temporanei impostare tempo di scadenza breve, pulizia automatica dei dati non più necessari. + +## Nodi di Combinazione Comuni + +|Tipo Nodo|Motivo Combinazione| |---|---| -|条件分支节点|根据数据加载结果判断是否存在特定数据，选择不同处理路径。| -|大模型调用节点|使用存储的上下文信息，提供更连贯的对话体验。| \ No newline at end of file +|Nodo Diramazione Condizionale|Secondo i risultati del caricamento dati giudicare se esistano dati specifici, scegliere percorsi di elaborazione diversi.| +|Nodo Chiamata Modello Grande|Utilizzare le informazioni di contesto memorizzate, fornire esperienze di conversazione più coerenti.| \ No newline at end of file diff --git a/docs/zh/tutorial/basic/node/Document-parsing.md b/docs/zh/tutorial/basic/node/Document-parsing.md index 578d145b1..8360936e0 100644 --- a/docs/zh/tutorial/basic/node/Document-parsing.md +++ b/docs/zh/tutorial/basic/node/Document-parsing.md @@ -1,136 +1,136 @@ -# 文档解析节点 +# Nodo Analisi Documenti 📄 -## 什么是文档解析节点？ +## Che cos'è il Nodo Analisi Documenti? -文档解析节点是您在 Magic Flow 中处理各类文件和数据源的"入口"，它就像一个智能阅读器，能够读取和理解不同格式的文档内容，将原始文件转换为后续节点可以处理的文本数据。无论是本地上传的 PDF、WORD 文件，还是网络上的网页内容，文档解析节点都能帮您提取出有价值的信息。 +Il Nodo Analisi Documenti è il vostro "ingresso" in Magic Flow per elaborare vari tipi di file e fonti dati, è come un lettore intelligente che può leggere e comprendere contenuti di documenti in diversi formati, convertendo file originali in dati di testo che i nodi successivi possono elaborare. Che si tratti di PDF, file WORD caricati localmente, o contenuti web online, il Nodo Analisi Documenti può aiutarvi a estrarre informazioni preziose. -**图片说明:** +**Spiegazione Immagine:** -文档解析节点界面主要由"显示名称"、"添加参数"选项、"参数值"和"表达式"设置区域组成。用户可以在此配置数据来源、文件类型及解析方式等参数。 -![文档解析节点](https://cdn.letsmagic.cn/static/img/Document-parsing.png) +L'interfaccia del Nodo Analisi Documenti è composta principalmente da aree di "Nome Visualizzato", "Aggiungi Parametro", "Valore Parametro" e impostazioni "Espressione". Gli utenti possono configurare qui parametri come fonte dati, tipo file e modalità di analisi. +![Nodo Analisi Documenti](https://cdn.letsmagic.cn/static/img/Document-parsing.png) -## 为什么需要文档解析节点？ +## Perché serve il Nodo Analisi Documenti? -在构建 AI 应用时，我们经常需要处理各种格式的文档和数据。文档解析节点解决了以下问题： -1. **格式转换**：将各种格式（PDF、DOCX、网页等）的文档转换为标准文本格式，方便后续处理 -2. **内容提取**：从复杂文件中提取出有价值的文本内容 -3. **统一入口**：为不同来源的数据（本地文件、网络内容、数据库等）提供统一的处理入口 -4. **预处理**：对原始数据进行初步清洗和格式化，提高后续分析的质量 +Nella costruzione di applicazioni AI, spesso abbiamo bisogno di elaborare documenti e dati in vari formati. Il Nodo Analisi Documenti risolve i seguenti problemi: +1. **Conversione Formato**: Convertire documenti in vari formati (PDF, DOCX, pagine web, ecc.) in formato testo standard, facilitando l'elaborazione successiva +2. **Estrazione Contenuto**: Estrarre contenuti testuali preziosi da file complessi +3. **Ingresso Unificato**: Fornire un ingresso di elaborazione unificato per dati da diverse fonti (file locali, contenuti web, database, ecc.) +4. **Pre-elaborazione**: Effettuare pulizia e formattazione preliminare dei dati originali, migliorare la qualità dell'analisi successiva -通过文档解析节点，您可以轻松将各种来源的数据转换为可供大模型理解和处理的文本形式，是构建知识问答、文档分析类应用的必备组件。 +Attraverso il Nodo Analisi Documenti, è possibile convertire facilmente dati da varie fonti in forma testuale comprensibile per i modelli grandi, è un componente essenziale per costruire applicazioni di question-answering basato su conoscenza, analisi documenti. -## 适用场景 +## Scenari di Applicazione -### 场景一：知识库问答系统 +### Scenario 1: Sistema Question-Answering Basato su Conoscenza -将公司内部文档、产品手册、培训资料等导入并解析，结合大模型节点构建基于企业知识的问答系统，帮助员工快速获取所需信息。 +Importare e analizzare documenti interni aziendali, manuali prodotto, materiali di formazione, ecc., combinandoli con nodi di modello grande per costruire sistemi di question-answering basati su conoscenza aziendale, aiutare i dipendenti a ottenere rapidamente le informazioni necessarie. -### 场景二：网页内容分析 +### Scenario 2: Analisi Contenuto Web -解析特定网页的内容，提取关键信息，用于市场分析、竞品监控或信息汇总。 +Analizzare il contenuto di pagine web specifiche, estrarre informazioni chiave, per analisi di mercato, monitoraggio concorrenti o riepilogo informazioni. -### 场景三：文档智能处理 +### Scenario 3: Elaborazione Intelligente Documenti -批量解析客户提交的文档（如简历、申请表等），提取关键信息并进行自动化处理和分类。 +Analizzare in batch documenti presentati dai clienti (come CV, moduli di richiesta, ecc.), estrarre informazioni chiave ed effettuare elaborazione e classificazione automatizzate. -## 节点参数说明 +## Spiegazione Parametri del Nodo -### 输入参数 +### Parametri di Input -文档解析节点主要有以下输入参数： -|参数名称|说明|是否必填|默认值| +Il Nodo Analisi Documenti ha principalmente i seguenti parametri di input: +|Nome Parametro|Spiegazione|Obbligatorio|Valore Default| |---|---|---|---| -|文件列表|需要解析的文件列表，可以是本地上传的文件、网络URL或变量引用|是|无| +|Lista File|Lista dei file da analizzare, può essere file caricati localmente, URL di rete o riferimento variabile|Sì|Nessuno| -### 输出变量 +### Variabili di Output -文档解析节点会输出以下变量，可在后续节点中使用： -|变量名|说明|示例值| +Il Nodo Analisi Documenti emetterà le seguenti variabili, utilizzabili nei nodi successivi: +|Nome Variabile|Spiegazione|Valore Esempio| |---|---|---| -|全部内容（content）|解析后的文本内容|"这是一份产品说明书，包含以下特点..."| -|文件（file_info）|文件的基本信息，包括文件名、文件地址、内容、类型等|`{"name": "产品手册.pdf", "size": 1024, "type": "application/pdf"}`| +|Tutto il Contenuto (content)|Contenuto testuale analizzato|"Questo è un manuale prodotto, contiene le seguenti caratteristiche..."| +|File (file_info)|Informazioni base del file, inclusi nome file, indirizzo file, contenuto, tipo, ecc.|`{"name": "Manuale_prodotto.pdf", "size": 1024, "type": "application/pdf"}`| -## 使用说明 +## Istruzioni per l'Uso -### 基本配置步骤 +### Passi di Configurazione Base -1. **添加文档解析节点** -2. **配置文件来源** - 1. 选择"文件上传"可上传本地文件 - 2. 选择"网络URL"可输入网页地址 - 3. 选择"变量"可使用之前节点输出的文件数据 -3. **连接下游节点** -将文档解析节点的输出连接到后续处理节点，例如文本切割节点、大模型调用节点等 +1. **Aggiungere Nodo Analisi Documenti** +2. **Configurare Fonte File** + 1. Selezionare "Caricamento File" per caricare file locali + 2. Selezionare "URL Rete" per inserire indirizzo web + 3. Selezionare "Variabile" per utilizzare dati file emessi da nodi precedenti +3. **Connettere Nodi Downstream** +Connettere l'output del nodo analisi documenti a nodi di elaborazione successivi, come nodo segmentazione testo, nodo chiamata modello grande, ecc. -### 进阶技巧 +### Tecniche Avanzate -1. **批量文件处理** -2. **动态URL解析** -3. **结合循环节点** -4. **条件解析** +1. **Elaborazione File in Batch** +2. **Analisi URL Dinamica** +3. **Combinazione con Nodo Ciclo** +4. **Analisi Condizionale** -## 注意事项 +## Note Importanti -### 文件大小限制 +### Limitazione Dimensione File -Magic Flow平台对上传文件有大小限制，通常不超过50MB。对于更大的文件，建议分割后上传或使用URL方式引入。 +La piattaforma Magic Flow ha limitazioni di dimensione per i file caricati, solitamente non superiori a 50MB. Per file più grandi, si consiglia di dividerli prima del caricamento o utilizzare il metodo URL per l'introduzione. -### 文件格式支持 +### Supporto Formati File -虽然文档解析节点支持多种格式，但不同格式的解析效果可能有差异： -- PDF文档：支持文本提取和表格识别 -- Word文档：支持完整文本和格式提取 -- 网页内容：支持HTML解析，但复杂JavaScript渲染的内容可能无法完全获取 -- 图片文件：需要通过OCR提取文字，准确率受图片质量影响 +Sebbene il Nodo Analisi Documenti supporti molteplici formati, l'effetto di analisi può differire per formati diversi: +- Documenti PDF: Supporta estrazione testo e riconoscimento tabelle +- Documenti Word: Supporta estrazione testo completo e formati +- Contenuti Web: Supporta analisi HTML, ma contenuti con rendering JavaScript complesso potrebbero non essere completamente acquisibili +- File Immagine: Necessitano estrazione testo tramite OCR, l'accuratezza è influenzata dalla qualità dell'immagine -### 网络资源访问 +### Accesso Risorse di Rete -通过URL解析网络内容时，请确保： -- URL是可公开访问的 -- 内容不需要登录验证 -- 资源不违反版权和法律法规 +Quando si analizza contenuto web tramite URL, assicurarsi che: +- L'URL sia accessibile pubblicamente +- Il contenuto non richieda autenticazione di login +- La risorsa non violi copyright e leggi -### 性能考虑 +### Considerazioni Prestazionali -解析大型文档或复杂格式可能需要较长时间，建议： -- 适当设置超时时间 -- 对大文档进行预处理或分割 -- 避免在一个流程中解析过多文件 +L'analisi di documenti di grandi dimensioni o formati complessi potrebbe richiedere tempo relativamente lungo, si consiglia: +- Impostare appropriatamente il tempo di timeout +- Pre-elaborare o dividere documenti di grandi dimensioni +- Evitare di analizzare troppi file in un singolo flusso -## 常见问题 +## Domande Frequenti -### 问题一：文档解析失败或内容缺失 +### Problema 1: Analisi documento fallita o contenuto mancante -**可能原因**：文件格式不兼容、文件损坏或加密、OCR识别失败 -**解决方案**： -- 检查文件是否可以正常打开 -- 尝试将文件转换为更通用的格式（如PDF转TXT） -- 对于加密文档，需要先解除加密后再上传 -- 提高图片质量或调整OCR参数 +**Possibili Cause**: Formato file incompatibile, file danneggiato o criptato, fallimento riconoscimento OCR +**Soluzioni**: +- Verificare se il file può essere aperto normalmente +- Provare a convertire il file in formato più universale (come PDF a TXT) +- Per documenti criptati, rimuovere prima la crittografia poi ricaricare +- Migliorare la qualità dell'immagine o regolare parametri OCR -### 问题二：解析时间过长 +### Problema 2: Tempo di analisi troppo lungo -**可能原因**：文件过大、格式复杂、网络资源加载慢 -**解决方案**： -- 分割大型文档为多个小文件 -- 增加超时时间设置 -- 对于网络资源，可以先下载到本地再上传解析 -- 简化处理流程，只提取必要内容 +**Possibili Cause**: File troppo grande, formato complesso, caricamento risorse di rete lento +**Soluzioni**: +- Dividere documenti di grandi dimensioni in molteplici file più piccoli +- Aumentare l'impostazione del tempo di timeout +- Per risorse di rete, è possibile scaricarle prima localmente poi caricarle per l'analisi +- Semplificare il flusso di elaborazione, estrarre solo contenuti necessari -### 问题三：特殊格式无法解析 +### Problema 3: Formati speciali non analizzabili -**可能原因**：非标准格式、新版本格式、专业软件格式 -**解决方案**： -- 将文件转换为标准格式后再上传 -- 使用专业软件导出为兼容格式 -- 结合代码节点自定义解析逻辑 -- 联系平台支持团队寻求技术帮助 +**Possibili Cause**: Formati non standard, formati di nuova versione, formati software professionale +**Soluzioni**: +- Convertire il file in formato standard prima del caricamento +- Utilizzare software professionale per esportare in formato compatibile +- Combinare con nodo codice per logica di analisi personalizzata +- Contattare il team di supporto della piattaforma per assistenza tecnica -## 常见搭配节点 +## Nodi di Combinazione Comuni -文档解析节点通常与以下节点配合使用： -1. **文本切割节点**：将解析出的长文本切割为适合大模型处理的片段 -2. **向量存储节点**：将解析的文档内容转换为向量并存储，用于后续相似度搜索 -3. **大模型调用节点**：使用大模型对解析的内容进行分析、总结或问答 -4. **代码节点**：对解析结果进行自定义处理和转换 -5. **条件节点**：根据解析结果的不同特征，选择不同的处理路径 \ No newline at end of file +Il Nodo Analisi Documenti solitamente si combina con i seguenti nodi: +1. **Nodo Segmentazione Testo**: Tagliare il testo lungo analizzato in frammenti adatti all'elaborazione del modello grande +2. **Nodo Memorizzazione Vettori**: Convertire il contenuto del documento analizzato in vettori e memorizzarli, per ricerche di similarità successive +3. **Nodo Chiamata Modello Grande**: Utilizzare il modello grande per analizzare, riassumere o rispondere al contenuto analizzato +4. **Nodo Codice**: Effettuare elaborazione e conversione personalizzate sui risultati di analisi +5. **Nodo Condizionale**: Secondo diverse caratteristiche dei risultati di analisi, scegliere percorsi di elaborazione diversi \ No newline at end of file diff --git a/docs/zh/tutorial/basic/node/HTTP-request.md b/docs/zh/tutorial/basic/node/HTTP-request.md index 541bd4339..7abf1b583 100644 --- a/docs/zh/tutorial/basic/node/HTTP-request.md +++ b/docs/zh/tutorial/basic/node/HTTP-request.md @@ -1,3 +1,172 @@ +# 🌐 Nodo Richiesta HTTP +## ❓ Cosa è il Nodo Richiesta HTTP? +Il nodo richiesta HTTP è un nodo importante nel flusso di lavoro Magic Flow utilizzato per interagire con API esterne e servizi di rete. È come un ponte per la comunicazione del flusso di lavoro con il mondo esterno, permette di inviare vari tipi di richieste di rete (come GET, POST, ecc.), ottenere dati esterni o sottoporre informazioni a sistemi esterni. Attraverso questo nodo, è possibile integrare facilmente servizi e fonti dati esterni nelle proprie applicazioni intelligenti. + +**Spiegazione Immagine:** + +L'interfaccia del nodo richiesta HTTP include aree di configurazione come URL richiesta, metodo richiesta, header richiesta e corpo richiesta, oltre a parti di impostazione risposta e output. Attraverso queste configurazioni, l'utente può definire come interagire con l'API esterna. +![Nodo Richiesta HTTP](https://cdn.letsmagic.cn/static/img/HTTP-request.png) + +## 🎯 Perché Serve il Nodo Richiesta HTTP? +Nella costruzione di applicazioni intelligenti, spesso è necessario ottenere dati esterni o interagire con altri sistemi, il nodo richiesta HTTP è progettato proprio per questo: +- **Ottenere Dati in Tempo Reale**: Ottenere le ultime informazioni da API esterne, come previsioni del tempo, tassi di cambio, quotazioni azionarie, ecc. +- **Integrazione di Sistema**: Interfacciarsi con sistemi interni aziendali o di terze parti, realizzare scambio dati cross-sistema +- **Attivare Servizi Esterni**: Chiamare servizi esterni per completare funzioni specifiche, come inviare SMS, notifiche push, ecc. +- **Sottomissione Dati**: Sottoporre dati di form o altre informazioni a sistemi esterni +- **Autenticazione**: Interfacciarsi con servizi di autenticazione di terze parti, come autenticazione OAuth + +## 📋 Scenari Applicabili +### 1. 📊 Applicazione Aggregazione Dati +Creare un'applicazione che aggrega informazioni da molteplici fonti dati, come integrare dati di vendita da diverse piattaforme in un unico report, fornire una visione completa per il decision-making. +### 2. 🏢 Integrazione Sistemi Interni Aziendali +Integrare il flusso di lavoro Magic Flow con sistemi interni aziendali (come CRM, ERP, OA, ecc.), realizzare circolazione dati e collaborazione operativa. +### 3. 🤖 Miglioramento Assistente Intelligente +Attraverso la chiamata di API professionali (come API meteo, API traduzione, ecc.), espandere i confini delle capacità dell'assistente intelligente, fornire servizi più ricchi. +### 4. 🔔 Sistema Trigger e Notifiche +Costruire un sistema capace di monitorare eventi specifici e attivare notifiche, come avvisi scorte, promemoria oscillazioni prezzi, ecc. + +## ⚙️ Spiegazione Parametri Nodo +### Parametri Base +|Nome Parametro|Spiegazione|Obbligatorio|Valore Default| +|---|---|---|---| +|URL Richiesta|Specificare l'indirizzo target della richiesta|Sì|Nessuno| +|Metodo Richiesta|Selezionare il metodo richiesta HTTP (GET/POST/PUT/DELETE, ecc.)|Sì|GET| +|Header Richiesta|Impostare informazioni header richiesta HTTP, come Content-Type, Authorization, ecc.|No|Nessuno| +|Corpo Richiesta|Quando si utilizzano metodi come POST/PUT, impostare i dati da inviare|No|Nessuno| + +#### Parametri Query +I parametri query vengono allegati all'URL in forma di coppie chiave-valore, formato `?key1=value1&key2=value2` +|Elemento Configurazione|Spiegazione| +|---|---| +|Nome Parametro|Nome del parametro query| +|Tipo Parametro|Tipo dati del parametro, come stringa, numero, ecc.| +|Valore Parametro|Valore specifico del parametro, supporta riferimento variabili| + +#### Parametri Path +I parametri path sono la parte dinamica nel percorso URL, comunemente utilizzati nelle API, come `/user/{id}` +|Elemento Configurazione|Spiegazione| +|---|---| +|Nome Parametro|Nome del parametro path| +|Nome Visualizzato|Nome parametro visualizzato nell'interfaccia| +|Tipo Parametro|Tipo dati del parametro| +|Valore Parametro|Valore specifico del parametro, supporta riferimento variabili| + +#### Corpo Richiesta (Body) +Il corpo richiesta viene utilizzato per inviare dati in richieste POST, PUT, ecc. +|Elemento Configurazione|Spiegazione| +|---|---| +|Tipo Contenuto|Formato del corpo richiesta, come JSON, Form, ecc.| +|Contenuto Corpo Richiesta|Contenuto specifico del corpo richiesta, diversi modi di editing in base al tipo di contenuto| + +#### Header Richiesta (Headers) +Gli header richiesta vengono utilizzati per inviare metadati della richiesta HTTP +|Elemento Configurazione|Spiegazione| +|---|---| +|Nome Parametro|Nome dell'header richiesta| +|Nome Visualizzato|Nome parametro visualizzato nell'interfaccia| +|Tipo Parametro|Tipo dati del parametro| +|Valore Parametro|Valore specifico del parametro, supporta riferimento variabili| + +### Impostazioni Output +|Elemento Configurazione|Spiegazione| +|---|---| +|Output Sistema|Il risultato della risposta alla richiesta HTTP verrà automaticamente memorizzato nell'output sistema| +|Output Personalizzato|È possibile estrarre parti specifiche del risultato della risposta come variabili personalizzate| + +## 📖 Istruzioni per l'Uso +### Passi di Configurazione Base +1. **Impostare URL Richiesta**： + 1. Inserire l'indirizzo API completo, includendo il protocollo ([http:// o https://](http:// o https://)) + 2. È possibile utilizzare riferimento variabili per URL dinamici, come `https://api.example.com/users/{{user_id}}` +2. **Selezionare Metodo Richiesta**： + 1. GET：Utilizzato per ottenere dati, come interrogare informazioni + 2. POST：Utilizzato per sottoporre dati, come creare record + 3. PUT：Utilizzato per aggiornare dati, come aggiornare informazioni utente + 4. DELETE：Utilizzato per eliminare dati +3. **Configurare Header Richiesta**： + 1. Impostare Content-Type (come application/json, multipart/form-data, ecc.) + 2. Aggiungere informazioni di autenticazione, come Authorization: Bearer token + 3. Altri header necessari come Accept, User-Agent, ecc. +4. **Scrivere Corpo Richiesta (applicabile a metodi POST/PUT, ecc.)**： + 1. Per formato JSON, è possibile utilizzare l'editor JSON + 2. È possibile fare riferimento a variabili, come `{"name": "{{user_name}}", "age": {{user_age}}}` +5. **Configurare Parsing Risposta**： + 1. Selezionare il formato risposta appropriato (JSON, XML, Text, ecc.) + 2. Impostare il percorso di estrazione dei dati risposta (se necessario) + +### Tecniche Avanzate +#### Elaborazione Dati JSON +L'elaborazione di API in formato JSON è lo scenario più comune： +1. **Inviare Dati JSON**： + 1. Impostare Content-Type come application/json + 2. Utilizzare il formato JSON corretto nel corpo richiesta +1. **Elaborare Risposta JSON**： + 1. Selezionare il modo di parsing risposta JSON + 2. È possibile estrarre campi specifici tramite percorso JSON, come `response.data.items` +2. **Elaborare Dati Annidati**： + 1. Per JSON complessi annidati, è possibile elaborarli ulteriormente in nodi successivi (come nodo esecuzione codice) + +#### Autenticazione e Sicurezza +L'interazione con API esterne generalmente richiede autenticazione： +1. **Autenticazione Base**： + 1. Utilizzare header Authorization: `Basic base64(username:password)` + 2. È possibile configurarlo direttamente negli header richiesta +2. **Autenticazione OAuth**： + 1. Ottenere token di accesso (potrebbe richiedere un nodo richiesta HTTP separato) + 2. Utilizzare nell'header Authorization: `Bearer your_access_token` +3. **Autenticazione Chiave API**： + 1. In base ai requisiti dell'API, potrebbe essere necessario aggiungere la chiave in parametri query URL, header richiesta o corpo richiesta + 2. Esempio：`https://api.example.com/data?api_key=your_api_key` +## ⚠️ Note di Attenzione +### Timeout e Performance +Le chiamate API esterne possono causare ritardi nell'esecuzione del flusso di lavoro： +- Impostare un timeout ragionevole per API importanti o potenzialmente lente +- Configurare un numero appropriato di tentativi per API instabili +- Considerare l'utilizzo di modalità asincrone per gestire richieste a lunga esecuzione + +### Gestione Errori +Le richieste di rete possono fallire per molteplici motivi： +- Configurare meccanismi di gestione errori corretti, come rami condizionali per giudicare lo stato della risposta +- Controllare i campi di output errore per ottenere informazioni dettagliate sugli errori +- Aggiungere meccanismi di fallback per flussi critici, come soluzioni alternative quando l'API non è disponibile + +### Sicurezza Dati +Attenzione nella gestione di dati sensibili： +- Evitare di includere informazioni sensibili negli URL (come password), utilizzare header o corpo richiesta +- Utilizzare protocollo HTTPS per garantire la crittografia della trasmissione dati +- Considerare l'utilizzo di variabili d'ambiente o sistemi di gestione chiavi per memorizzare informazioni sensibili come chiavi API + +## ❓ Domande Frequenti +### Domanda 1: Come Gestire i Problemi di Limitazione API? +**Soluzioni**：Molteplici API hanno limiti di frequenza di chiamata, è possibile： +- Implementare controllo velocità richieste, evitare di inviare troppe richieste in breve tempo +- Gestire correttamente il codice di stato 429 (Too Many Requests), aggiungere logica di attesa +- Quando possibile, considerare la cache dei dati per ridurre le chiamate API + +### Domanda 2: Cosa Fare se il Formato dei Dati Restituiti dalla Richiesta non è Corretto? +**Soluzioni**：Quando il formato dati non corrisponde alle aspettative： +- Verificare se il modo di parsing della risposta è corretto (JSON/XML/Text) +- Utilizzare il nodo esecuzione codice per conversioni e elaborazioni dei dati +- Confermare la documentazione API, verificare se i parametri richiesta sono corretti + +### Domanda 3: Come Trasmettere File o Dati Binari? +**Soluzioni**：La trasmissione di file richiede elaborazioni speciali： +- Impostare Content-Type come multipart/form-data +- Utilizzare il formato corpo richiesta corretto per incapsulare i dati del file +- Per file di grandi dimensioni, prestare attenzione alle impostazioni di timeout della richiesta + +## 🌟 Migliori Pratiche +### Nodi di Combinazione Comuni +|Tipo di Nodo|Motivo di Combinazione| +|---|---| +|Nodo Esecuzione Codice|Elaborare dati di risposta, convertire formati o estrarre informazioni chiave| +|Nodo Ramo Condizionale|Decidere l'operazione successiva in base allo stato della risposta API o al contenuto| +|Nodo Chiamata Modello Grande|Fornire i dati ottenuti dall'API come contesto al modello grande| +|Nodo Salvataggio Variabili|Salvare dati chiave restituiti dall'API per l'utilizzo nei flussi successivi| +|Nodo Ciclo|Elaborare API con paginazione o richieste batch di molteplici risorse| + +--- + # HTTP请求节点 ## 什么是HTTP请求节点？ HTTP请求节点是Magic Flow工作流中用于与外部API和网络服务进行交互的重要节点。它就像是您的工作流与外部世界沟通的桥梁，允许您发送各种网络请求（如GET、POST等），获取外部数据或向外部系统提交信息。通过这个节点，您可以轻松地将外部服务和数据源集成到您的智能应用中。 diff --git a/docs/zh/tutorial/basic/node/Historical-message-query.md b/docs/zh/tutorial/basic/node/Historical-message-query.md index 117911b5c..86abfc901 100644 --- a/docs/zh/tutorial/basic/node/Historical-message-query.md +++ b/docs/zh/tutorial/basic/node/Historical-message-query.md @@ -1,86 +1,102 @@ -# 历史消息查询节点 +# Nodo Interrogazione Messaggi Storici 📜 -## 什么是历史消息查询节点？ -历史消息查询节点是 Magic Flow 中用于检索历史对话记录的功能节点。它就像一个智能记忆库，帮助您从过去的对话中提取重要信息，实现对历史交互内容的快速查询和分析。 +## Che cos'è il Nodo Interrogazione Messaggi Storici? -**界面说明：** +Il Nodo Interrogazione Messaggi Storici è un nodo funzionale in Magic Flow utilizzato per recuperare registri di conversazioni storiche. È come una libreria di memoria intelligente che aiuta a estrarre informazioni importanti dalle conversazioni passate, realizzando interrogazioni e analisi rapide dei contenuti di interazioni storiche. -历史消息查询节点界面展示了节点的主要配置区域，包括最大记录数设置区和时间范围筛选区。最大数量默认设置为10条记录，时间范围可以通过选择起始和结束日期自定义。底部输出区显示查询结果将包含历史消息列表(history_messages)、消息角色(role)和消息内容(content)。 -![历史消息查询节点](https://cdn.letsmagic.cn/static/img/Historical-message-query.png) +**Spiegazione Interfaccia:** -## 为什么需要历史消息查询节点？ -在智能对话系统中，理解上下文和历史交互是提供连贯、个性化服务的关键。历史消息查询节点帮助您： -1. **追踪对话流程**：快速检索之前的通信内容，理解当前对话上下文 -2. **提取关键信息**：从历史记录中找出用户已经提供的重要信息，避免重复询问 -3. **分析用户习惯**：通过历史交互记录了解用户偏好和行为模式 -4. **实现连续对话**：基于历史对话构建连贯的交互体验，提高用户满意度 +L'interfaccia del Nodo Interrogazione Messaggi Storici mostra le aree di configurazione principali del nodo, inclusa l'area di impostazione numero massimo record e l'area di filtro per intervallo temporale. Il numero massimo è impostato di default a 10 record, l'intervallo temporale può essere personalizzato selezionando date di inizio e fine. L'area di output in basso mostra che i risultati della query conterranno lista messaggi storici (history_messages), ruolo messaggio (role) e contenuto messaggio (content). +![Nodo Interrogazione Messaggi Storici](https://cdn.letsmagic.cn/static/img/Historical-message-query.png) -## 应用场景 -### 场景一：个性化客服机器人 -客服机器人需要了解用户之前的咨询内容和提供的解决方案，避免重复回答或给出矛盾信息。通过历史消息查询节点，系统可以检索用户之前的咨询记录，提供连贯的服务体验。 +## Perché serve il Nodo Interrogazione Messaggi Storici? -### 场景二：学习助手记忆功能 -在教育应用中，学习助手需要记住学生之前的学习内容和问题。历史消息查询节点可以帮助检索学生之前的学习记录，为个性化学习推荐提供基础。 +Nei sistemi di conversazione intelligente, comprendere il contesto e le interazioni storiche è la chiave per fornire servizi coerenti e personalizzati. Il Nodo Interrogazione Messaggi Storici aiuta a: +1. **Tracciare il Flusso di Conversazione**: Recuperare rapidamente contenuti di comunicazione precedenti, comprendere il contesto della conversazione corrente +2. **Estrarre Informazioni Chiave**: Trovare dalle registrazioni storiche informazioni importanti già fornite dall'utente, evitare domande ripetitive +3. **Analizzare Abitudini Utente**: Comprendere preferenze e modelli di comportamento dell'utente attraverso registrazioni di interazioni storiche +4. **Realizzare Conversazione Continua**: Costruire esperienze di interazione coerenti basate su conversazioni storiche, migliorare la soddisfazione dell'utente -### 场景三：多轮对话中的上下文管理 -在复杂的多轮对话场景中，对话内容可能涉及多个话题。历史消息查询节点可以帮助提取特定话题的历史对话段落，维持对话的连贯性和上下文完整性。 +## Scenari di Applicazione -## 节点参数说明 -### 输入参数 -历史消息查询节点的输入参数用于设置查询条件，主要包括： -|参数名称|说明|是否必填|默认值| +### Scenario 1: Robot Assistenza Clienti Personalizzato +Il robot assistenza clienti necessita di conoscere contenuti di consultazione precedenti dell'utente e soluzioni fornite, per evitare risposte ripetitive o contraddittorie. Attraverso il Nodo Interrogazione Messaggi Storici, il sistema può recuperare registrazioni di consultazione precedenti dell'utente, fornire esperienze di servizio coerenti. + +### Scenario 2: Funzione Memoria Assistente di Apprendimento +Nelle applicazioni educative, l'assistente di apprendimento necessita di ricordare contenuti di apprendimento e problemi precedenti dello studente. Il Nodo Interrogazione Messaggi Storici può aiutare a recuperare registrazioni di apprendimento precedenti dello studente, fornire basi per raccomandazioni di apprendimento personalizzate. + +### Scenario 3: Gestione Contesto in Conversazioni Multi-turno +In scenari di conversazioni multi-turno complesse, i contenuti di conversazione potrebbero coinvolgere molteplici argomenti. Il Nodo Interrogazione Messaggi Storici può aiutare a estrarre paragrafi di conversazione storica relativi ad argomenti specifici, mantenere coerenza e integrità del contesto della conversazione. + +## Spiegazione Parametri del Nodo + +### Parametri di Input + +I parametri di input del Nodo Interrogazione Messaggi Storici sono utilizzati per impostare condizioni di query, includono principalmente: +|Nome Parametro|Spiegazione|Obbligatorio|Valore Default| |---|---|---|---| -|最大数量|限制返回的历史消息记录数量|是|10| -|时间范围筛选|设置查询时间区间，包括起始日期和结束日期|否|无| +|Numero Massimo|Limitare il numero di record di messaggi storici restituiti|Sì|10| +|Filtro Intervallo Temporale|Impostare l'intervallo di tempo della query, inclusi data di inizio e data di fine|No|Nessuno| + +### Parametri di Output -### 输出参数 -查询结果将作为节点的输出参数，可用于后续节点： -|参数名称|说明|数据类型| +I risultati della query saranno utilizzati come parametri di output del nodo, per nodi successivi: +|Nome Parametro|Spiegazione|Tipo Dati| |---|---|---| -|历史消息(history_messages)|历史消息记录列表|数组| -|角色(role)|消息发送者角色（如用户、系统）|字符串| -|内容(content)|消息内容|字符串| - -## 使用说明 -### 基本配置步骤 -1. **添加节点**：将历史消息查询节点拖入工作流编辑器 -2. **设置最大数量**：在"最大数量"输入框中输入需要查询的历史消息数量（建议设置合理值，如10-20条记录） -3. **设置时间范围**（可选）：如需时间筛选，点击时间范围选择器设置起始和结束日期 -4. **连接节点**：将历史消息查询节点与前置节点（如开始或触发节点）和后续节点（如大模型调用节点）连接 - -### 高级技巧 -1. **精确时间控制**：对于需要高精度时间筛选的场景，可以设置精确的时间范围，获取特定时间段的对话记录 -2. **结合变量使用**：可以将查询结果`history_messages`保存到变量中，供后续节点使用 -3. **与大模型节点结合**：将历史消息查询结果作为大模型调用节点的输入，实现基于历史对话的智能回复 - -## 重要提示 -### 性能考量 -- **查询数量限制**：设置过大的历史消息数量可能会降低工作流执行效率；建议根据实际需求设置合理的最大数量 -- **时间范围设置**：过大的时间范围可能会返回过多无关消息，影响后续分析效率 - -### 内容安全 -- **敏感信息处理**：历史消息可能包含敏感信息，在将查询结果传递给后续节点时要考虑信息安全 -- **数据使用合规**：确保历史消息的使用符合隐私保护法规 - -## 常见问题 -### 查询结果为空 -**问题**：配置了历史消息查询节点但得到空结果。 -**解决方案**： -1. 检查时间范围设置是否正确，确保查询时间范围内有对话记录 -2. 确认前置节点是否正确传递了会话信息 -3. 考虑放宽查询条件，如扩大时间范围或增加最大数量 - -### 查询结果不完整 -**问题**：查询结果中缺少一些预期的历史消息。 -**解决方案**： -1. 增加最大数量设置，确保检索足够多的历史记录 -2. 检查时间范围设置，确保覆盖所有需要的历史消息时间段 -3. 确认历史消息是否正确存储在系统中 - -## 常见配对节点 -|节点类型|配对说明| +|Messaggi Storici (history_messages)|Lista registrazioni messaggi storici|Array| +|Ruolo (role)|Ruolo mittente messaggio (come utente, sistema)|Stringa| +|Contenuto (content)|Contenuto del messaggio|Stringa| + +## Istruzioni per l'Uso + +### Passi di Configurazione Base + +1. **Aggiungere Nodo**: Trascinare il nodo interrogazione messaggi storici nell'editor del flusso di lavoro +2. **Impostare Numero Massimo**: Nella casella di input "Numero Massimo" inserire il numero di messaggi storici da interrogare (si consiglia di impostare valori ragionevoli, come 10-20 record) +3. **Impostare Intervallo Temporale** (opzionale): Se necessario filtrare per tempo, cliccare il selettore intervallo temporale per impostare date di inizio e fine +4. **Connettere Nodi**: Connettere il nodo interrogazione messaggi storici con nodi precedenti (come nodi di inizio o trigger) e nodi successivi (come nodi chiamata modello grande) + +### Tecniche Avanzate + +1. **Controllo Temporale Preciso**: Per scenari che richiedono filtri temporali ad alta precisione, è possibile impostare intervalli temporali precisi, ottenere registrazioni di conversazione di periodi specifici +2. **Combinazione con Variabili**: È possibile salvare i risultati della query `history_messages` in variabili, per l'utilizzo in nodi successivi +3. **Combinazione con Nodo Modello Grande**: Utilizzare i risultati dell'interrogazione messaggi storici come input del nodo chiamata modello grande, realizzare risposte intelligenti basate su conversazioni storiche + +## Note Importanti + +### Considerazioni Prestazionali + +- **Limitazione Numero Query**: Impostare numeri troppo grandi di messaggi storici potrebbe ridurre l'efficienza di esecuzione del flusso di lavoro; si consiglia di impostare numeri massimi ragionevoli secondo le esigenze effettive +- **Impostazione Intervallo Temporale**: Intervalli temporali troppo ampi potrebbero restituire troppi messaggi irrilevanti, influenzare l'efficienza dell'analisi successiva + +### Sicurezza Contenuto + +- **Gestione Informazioni Sensibili**: I messaggi storici potrebbero contenere informazioni sensibili, considerare la sicurezza delle informazioni quando si passano i risultati della query a nodi successivi +- **Uso Dati Conforme**: Assicurarsi che l'uso dei messaggi storici sia conforme alle normative sulla protezione della privacy + +## Domande Frequenti + +### Risultati Query Vuoti + +**Problema**: È stato configurato il nodo interrogazione messaggi storici ma si ottengono risultati vuoti. +**Soluzioni**: +1. Verificare che l'impostazione dell'intervallo temporale sia corretta, assicurarsi che nell'intervallo di tempo della query ci siano registrazioni di conversazione +2. Confermare che i nodi precedenti abbiano passato correttamente le informazioni di sessione +3. Considerare di allentare le condizioni di query, come ampliare l'intervallo temporale o aumentare il numero massimo + +### Risultati Query Incompleti + +**Problema**: Nei risultati della query mancano alcuni messaggi storici previsti. +**Soluzioni**: +1. Aumentare l'impostazione del numero massimo, assicurarsi di recuperare registrazioni storiche sufficienti +2. Verificare l'impostazione dell'intervallo temporale, assicurarsi di coprire tutti i periodi di tempo dei messaggi storici necessari +3. Confermare che i messaggi storici siano stati correttamente memorizzati nel sistema + +## Nodi di Combinazione Comuni + +|Tipo Nodo|Spiegazione Combinazione| |---|---| -|大模型调用节点|向大模型提供历史消息，实现基于上下文的智能回复| -|条件分支节点|根据历史消息内容做出决策，选择不同的处理路径| -|代码执行节点|对历史消息进行深度分析和处理| -|消息回复节点|基于历史分析结果构建回复内容| \ No newline at end of file +|Nodo Chiamata Modello Grande|Fornire al modello grande messaggi storici, realizzare risposte intelligenti basate su contesto| +|Nodo Diramazione Condizionale|Prendere decisioni secondo i contenuti dei messaggi storici, scegliere percorsi di elaborazione diversi| +|Nodo Esecuzione Codice|Effettuare analisi e elaborazione approfondite dei messaggi storici| +|Nodo Risposta Messaggio|Costruire contenuti di risposta basati sui risultati dell'analisi storica| \ No newline at end of file diff --git a/docs/zh/tutorial/basic/node/Historical-message-storage.md b/docs/zh/tutorial/basic/node/Historical-message-storage.md index c4633ca71..3fca3c301 100644 --- a/docs/zh/tutorial/basic/node/Historical-message-storage.md +++ b/docs/zh/tutorial/basic/node/Historical-message-storage.md @@ -1,85 +1,105 @@ -# 历史消息存储节点 +# Nodo Memorizzazione Messaggi Storici 💾 -## 什么是历史消息存储节点？ -历史消息存储节点是 Magic Flow 工作流中用于记录和保存对话消息的功能节点。它就像一个内存存储单元，可以将指定的文本信息保存到对话历史中，以便后续查询和使用。这些存储的消息可以在后续交互中检索，为 AI 助手提供会话记忆能力。 +## Che cos'è il Nodo Memorizzazione Messaggi Storici? -**界面说明：** +Il Nodo Memorizzazione Messaggi Storici è un nodo funzionale in Magic Flow utilizzato per registrare e salvare messaggi di conversazione. È come un'unità di memoria che può salvare informazioni testuali specificate nella cronologia della conversazione, per essere recuperate e utilizzate successivamente. Questi messaggi memorizzati possono essere recuperati nelle interazioni successive, fornendo all'assistente AI capacità di memoria di sessione. -顶部区域用于消息类型选择，目前支持文本、图片和文件卡片类型消息；底部区域用于消息内容输入，支持使用"@"添加变量实现动态内容存储。 -![历史消息存储节点](https://cdn.letsmagic.cn/static/img/Historical-message-storage.png) +**Spiegazione Interfaccia:** -## 为什么需要历史消息存储节点？ -在智能对话系统中，记忆和上下文管理是提供连贯交互体验的关键。历史消息存储节点帮助您： -1. **构建 AI 助手记忆**：让 AI 助手"记住"重要信息，无需用户重复提供 -2. **保存中间结果**：存储工作流中的关键数据和中间结果，供后续流程引用 -3. **维持对话连贯性**：通过存储上下文信息，确保对话的连续性和上下文感知 -4. **创建用户画像**：记录用户提供的关键信息，逐步构建用户画像，提供个性化体验 +L'area superiore è utilizzata per la selezione del tipo di messaggio, attualmente supporta tipi di messaggio testo, immagine e scheda file; l'area inferiore è utilizzata per l'input del contenuto del messaggio, supporta l'utilizzo di "@" per aggiungere variabili per realizzare memorizzazione dinamica del contenuto. +![Nodo Memorizzazione Messaggi Storici](https://cdn.letsmagic.cn/static/img/Historical-message-storage.png) -## 应用场景 -### 场景一：用户信息收集与记忆 -在用户首次提供个人信息（如姓名、偏好等）后，可以使用历史消息存储节点记录这些信息。在后续对话中，系统可以直接使用这些记忆，避免重复询问，提升用户体验。 +## Perché serve il Nodo Memorizzazione Messaggi Storici? -### 场景二：多轮对话记忆管理 -在复杂的多轮对话场景中，某些关键信息需要在多个对话轮次中使用。通过历史消息存储节点，可以有选择地保存重要内容，而不仅仅依赖自动记忆的近期消息。 +Nei sistemi di conversazione intelligente, la memoria e la gestione del contesto sono la chiave per fornire esperienze di interazione coerenti. Il Nodo Memorizzazione Messaggi Storici aiuta a: +1. **Costruire Memoria Assistente AI**: Far "ricordare" all'assistente AI informazioni importanti, senza bisogno che l'utente le fornisca ripetutamente +2. **Salvare Risultati Intermedi**: Memorizzare dati chiave e risultati intermedi nel flusso di lavoro, per riferimento nei processi successivi +3. **Mantenere Coerenza Conversazione**: Attraverso la memorizzazione di informazioni contestuali, garantire continuità e consapevolezza del contesto della conversazione +4. **Creare Profilo Utente**: Registrare informazioni chiave fornite dall'utente, costruire gradualmente un profilo utente, fornire esperienze personalizzate -### 场景三：工作流状态记录 -在处理工单、审批等场景中，可以使用历史消息存储节点记录每一步的状态和结果，形成完整的处理记录，便于后续查询和追踪。 +## Scenari di Applicazione -## 节点参数说明 -### 输入参数 -**历史消息存储节点的主要输入参数包括：** -|参数名称|说明|是否必填|默认值| +### Scenario 1: Raccolta e Memoria Informazioni Utente + +Dopo che l'utente fornisce per la prima volta informazioni personali (come nome, preferenze, ecc.), è possibile utilizzare il Nodo Memorizzazione Messaggi Storici per registrare queste informazioni. Nelle conversazioni successive, il sistema può utilizzare direttamente questi ricordi, evitando domande ripetitive, migliorando l'esperienza utente. + +### Scenario 2: Gestione Memoria Conversazioni Multi-turno + +In scenari di conversazioni multi-turno complesse, alcune informazioni chiave necessitano di essere utilizzate in molteplici turni di conversazione. Attraverso il Nodo Memorizzazione Messaggi Storici, è possibile salvare selettivamente contenuti importanti, piuttosto che affidarsi solo alla memoria automatica dei messaggi recenti. + +### Scenario 3: Registrazione Stato Flusso di Lavoro + +In scenari di elaborazione ticket, approvazioni, ecc., è possibile utilizzare il Nodo Memorizzazione Messaggi Storici per registrare lo stato e i risultati di ogni passo, formare registrazioni complete di elaborazione, facilitando query e tracciamento successivi. + +## Spiegazione Parametri del Nodo + +### Parametri di Input + +**I principali parametri di input del Nodo Memorizzazione Messaggi Storici includono:** +|Nome Parametro|Spiegazione|Obbligatorio|Valore Default| |---|---|---|---| -|消息类型|目前支持文本、图片和文件卡片类型消息|是|文本| -|消息内容|要存储的文本信息，支持变量引用|是|无| - -### 输出内容 -历史消息存储节点没有标准的输出参数；其主要功能是将内容写入系统的历史消息记录中。 - -## 使用说明 -### 基本配置步骤 -1. **添加节点**：将历史消息存储节点拖入工作流编辑器 -2. **选择消息类型**：从消息类型下拉菜单中选择"文本" -3. **编写消息内容**：在消息内容输入框中输入要存储的文本 - 1. 可以直接输入固定文本，如"已记录用户偏好" - 2. 也可以使用"@"符号引用变量，如"用户偏好：@user_preference" -4. **连接节点**：将历史消息存储节点与前置节点（如条件分支或代码执行节点）和后续节点连接起来 - -### 高级技巧 -1. **组合变量使用**：消息内容支持多个变量组合，构建结构化的记忆内容 -2. **使用条件筛选**：与条件分支节点配合，仅在特定条件满足时存储信息 -3. **格式化存储内容**：使用格式良好的文本模板，便于后续检索和处理 - -## 重要提示 -### 存储数量限制 -- **适度存储**：不要存储过多不必要的信息，可能导致历史记录过长 -- **关注重点**：只存储对后续交互有价值的关键信息，提高存储效率 - -### 内容安全 -- **敏感信息处理**：避免存储用户隐私和敏感信息，如密码、详细联系方式等 -- **合规使用**：确保存储的内容符合数据隐私法规 - -### 内容格式 -- **清晰结构**：设计结构化的存储格式，便于后续检索和理解 -- **长度控制**：过长的内容在后续查询中可能难以处理，建议控制合理长度 - -## 常见问题 -### 在后续流程中找不到存储的内容 -**解决方案**： -1. 确认工作流执行顺序正确；存储节点必须在查询节点之前执行 -2. 检查历史消息查询节点的时间范围设置，确保涵盖存储消息的时间点 -3. 增加历史消息查询节点的最大记录数设置，确保覆盖存储的消息 - -### 存储的变量内容不正确 -**解决方案**： -1. 检查变量引用是否正确，确保使用正确的变量名 -2. 验证前置节点是否成功输出预期的变量值 -3. 使用代码执行节点打印变量内容进行调试，确认工作流中的变量传递正确 - -## 常见配对节点 -|节点类型|配对说明| +|Tipo Messaggio|Attualmente supporta tipi di messaggio testo, immagine e scheda file|Sì|Testo| +|Contenuto Messaggio|Le informazioni testuali da memorizzare, supporta riferimento variabili|Sì|Nessuno| + +### Contenuto di Output + +Il Nodo Memorizzazione Messaggi Storici non ha parametri di output standard; la sua funzione principale è scrivere il contenuto nei registri di messaggi storici del sistema. + +## Istruzioni per l'Uso + +### Passi di Configurazione Base + +1. **Aggiungere Nodo**: Trascinare il nodo memorizzazione messaggi storici nell'editor del flusso di lavoro +2. **Selezionare Tipo Messaggio**: Dal menu a tendina del tipo di messaggio selezionare "Testo" +3. **Scrivere Contenuto Messaggio**: Nella casella di input del contenuto del messaggio inserire il testo da memorizzare + 1. È possibile inserire direttamente testo fisso, come "Preferenze utente registrate" + 2. È anche possibile utilizzare il simbolo "@" per referenziare variabili, come "Preferenza utente: @user_preference" +4. **Connettere Nodi**: Connettere il nodo memorizzazione messaggi storici con nodi precedenti (come diramazione condizionale o esecuzione codice) e nodi successivi + +### Tecniche Avanzate + +1. **Utilizzo Combinato Variabili**: Il contenuto del messaggio supporta combinazione di molteplici variabili, costruire contenuti di memoria strutturati +2. **Utilizzo Filtraggio Condizionale**: In combinazione con il nodo diramazione condizionale, memorizzare informazioni solo quando condizioni specifiche sono soddisfatte +3. **Formattazione Contenuto Memorizzato**: Utilizzare template di testo ben formattati, facilitare recupero e elaborazione successivi + +## Note Importanti + +### Limitazioni Quantità Memorizzazione + +- **Memorizzazione Adeguata**: Non memorizzare troppe informazioni non necessarie, potrebbe causare eccessiva lunghezza dei registri storici +- **Focus sui Punti Chiave**: Memorizzare solo informazioni chiave che hanno valore per le interazioni successive, migliorare l'efficienza di memorizzazione + +### Sicurezza Contenuto + +- **Gestione Informazioni Sensibili**: Evitare di memorizzare privacy utente e informazioni sensibili, come password, dettagliati contatti, ecc. +- **Uso Conforme**: Assicurarsi che il contenuto memorizzato sia conforme alle normative sulla privacy dei dati + +### Formato Contenuto + +- **Struttura Chiara**: Progettare formato di memorizzazione strutturato, facilitare recupero e comprensione successivi +- **Controllo Lunghezza**: Contenuti troppo lunghi potrebbero essere difficili da elaborare nelle query successive, si consiglia di controllare lunghezze ragionevoli + +## Domande Frequenti + +### Non riesco a trovare il contenuto memorizzato nei processi successivi + +**Soluzioni**: +1. Confermare che l'ordine di esecuzione del flusso di lavoro sia corretto; il nodo di memorizzazione deve essere eseguito prima del nodo di query +2. Verificare l'impostazione dell'intervallo temporale del nodo interrogazione messaggi storici, assicurarsi di coprire il punto temporale del messaggio memorizzato +3. Aumentare l'impostazione del numero massimo record del nodo interrogazione messaggi storici, assicurarsi di coprire il messaggio memorizzato + +### Il contenuto della variabile memorizzata non è corretto + +**Soluzioni**: +1. Verificare che il riferimento alla variabile sia corretto, assicurarsi di utilizzare il nome variabile corretto +2. Validare che i nodi precedenti abbiano emesso con successo i valori variabili previsti +3. Utilizzare il nodo esecuzione codice per stampare il contenuto delle variabili per debug, confermare che il passaggio delle variabili nel flusso di lavoro sia corretto + +## Nodi di Combinazione Comuni + +|Tipo Nodo|Spiegazione Combinazione| |---|---| -|历史消息查询节点|存储和查询配合使用，实现完整的记忆管理| -|大模型调用节点|向大模型提供存储的历史信息，增强上下文理解| -|条件分支节点|根据条件决定是否存储特定信息| -|代码执行节点|处理和格式化要存储的内容| \ No newline at end of file +|Nodo Interrogazione Messaggi Storici|Utilizzo combinato di memorizzazione e interrogazione, realizzare gestione memoria completa| +|Nodo Chiamata Modello Grande|Fornire al modello grande informazioni storiche memorizzate, migliorare comprensione del contesto| +|Nodo Diramazione Condizionale|Decidere secondo condizioni se memorizzare informazioni specifiche| +|Nodo Esecuzione Codice|Elaborare e formattare il contenuto da memorizzare| \ No newline at end of file diff --git a/docs/zh/tutorial/basic/node/Image-generation.md b/docs/zh/tutorial/basic/node/Image-generation.md index df6d4786a..f4399b196 100644 --- a/docs/zh/tutorial/basic/node/Image-generation.md +++ b/docs/zh/tutorial/basic/node/Image-generation.md @@ -1,3 +1,134 @@ +# 🖼️ Nodo Generazione Immagini + +## ❓ Cos'è il Nodo Generazione Immagini? + +Il nodo Generazione Immagini è uno strumento potente fornito dalla piattaforma Magic Flow che può generare automaticamente immagini di alta qualità basate sulle descrizioni testuali (prompt) che fornisci. È come comunicare con un pittore professionista: descrivi l'immagine che vuoi e il pittore la disegnerà per te. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Generazione Immagini è composta dall'area di selezione del modello in alto e dall'area di configurazione dei parametri in basso. In alto puoi selezionare diversi modelli di generazione immagini; in basso puoi impostare il prompt (descrivi l'immagine che vuoi), le dimensioni dell'immagine, il rapporto dimensioni, ecc. +![Nodo Generazione Immagini](https://cdn.letsmagic.cn/static/img/Image-generation.png) + +## 🤔 Perché Serve il Nodo Generazione Immagini? + +**Nei flussi di lavoro intelligenti, potresti aver bisogno di:** +- Generare automaticamente immagini di presentazione del prodotto basate sulle descrizioni fornite dagli utenti +- Fornire materiale visivo per la creazione di contenuti, come generare poster di marketing, illustrazioni, ecc. +- Fornire espressioni visive basate sui contenuti testuali +- Creare rapidamente prototipi o disegni concettuali + +Il nodo Generazione Immagini può aiutarti a ottenere rapidamente le risorse immagine necessarie attraverso semplici descrizioni testuali senza bisogno di competenze di design professionale, migliorando notevolmente l'efficienza lavorativa. + +## 🎯 Scenari Applicabili + +### Scenario 1: Generazione Automatica di Immagini di Presentazione Prodotto +Quando gli utenti descrivono l'aspetto del prodotto che desiderano, il sistema può generare automaticamente disegni concettuali del prodotto che corrispondono alla descrizione, aiutando gli utenti a comprendere il prodotto in modo più intuitivo. + +### Scenario 2: Assistenza alla Creazione di Contenuti +Generare automaticamente contenuti immagine correlati per articoli di blog, post sui social media o materiali di marketing, migliorando l'attrattiva e l'impatto dei contenuti. + +### Scenario 3: Acquisizione di Ispirazione per il Design +Durante il processo di design, generare rapidamente molteplici schemi di design attraverso descrizioni testuali, come fonte di ispirazione o prototipo preliminare. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri di Input +|Nome Parametro|Spiegazione|Obbligatorio|Valore Predefinito| +|---|---|---|---| +|**Modello**|Seleziona il modello AI da utilizzare per generare l'immagine, modelli diversi hanno stili e caratteristiche diverse|Sì|Midjourney| +|**Prompt**|Descrivi il contenuto dell'immagine che vuoi generare, più dettagliato meglio è|Sì|Nessuno| +|**Rapporto Dimensioni**|Rapporto preimpostato delle dimensioni dell'immagine, come 1:1 (quadrato), 16:9 (schermo largo), ecc.|No|1:1| +|**Immagine di Riferimento**|Carica un'immagine di riferimento, l'AI farà riferimento al suo stile o contenuto per creare|No|Nessuna| + +### Spiegazione Output +|Nome Parametro|Spiegazione| +|---|---| +|**Link Immagine (**image_url**)**|Dopo che il modello grande genera l'immagine, restituisce l'indirizzo immagine corrispondente| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Seleziona il modello appropriato**: + 1. Serie Midjourney: Adatta per stili artistici, disegni concettuali, contenuti altamente creativi + 2. Serie Flux: Adatta per stili realistici, immagini di prodotto, illustrazioni dettagliate + 3. Volcengine: Adatta per scenari cinesi, immagini in stile orientale +2. **Scrivi prompt efficaci**: + 1. Descrivi nel dettaglio il contenuto dell'immagine che vuoi, stile, colori, ecc. + 2. Usa aggettivi specifici per aumentare la precisione + 3. Ad esempio: "Un cane Samoiedo dal pelo dorato seduto su un prato verde, sfondo cielo blu con nuvole bianche, sole splendente, stile fotografico" +3. **Imposta parametri immagine appropriati**: **Carica immagine di riferimento (opzionale)**: + 1. Se hai un'immagine di riferimento di stile specifico, puoi caricarla per aiutare l'AI a comprendere meglio le tue esigenze + +### Tecniche Avanzate +1. **Ingegneria dei Prompt**: + 1. Usa nomi di artisti per guidare lo stile: "...in stile Van Gogh", "...in stile cyberpunk" + 2. Aggiungi descrizioni di medium per migliorare l'effetto: "dipinto ad olio", "acquerello", "foto", "rendering 3D" +2. **Scelta del Rapporto Dimensioni**: + 1. Ritratti adatti per proporzioni verticali (come 3:4) + 2. Paesaggi adatti per proporzioni orizzontali (come 16:9) + 3. Presentazioni prodotto generalmente usano quadrato (1:1) +3. **Utilizzo Combinato di Modelli**: + 1. Prima usa Midjourney per generare disegni concettuali creativi + 2. Poi usa la serie Flux per raffinamenti dettagliati + +## ⚠️ Note Importanti + +### Velocità e Qualità di Generazione +I diversi modelli hanno velocità e qualità variabili: +- Midjourney-Turbo: Più veloce, ma qualità relativamente inferiore +- Midjourney-Relax: Velocità media, buona qualità +- Flux1-Pro: Più lento, ma dettagli e qualità superiori + +Bilancia velocità e qualità secondo le tue esigenze. + +### Limitazioni di Contenuto +La generazione di immagini ha alcune limitazioni di contenuto. I seguenti tipi di prompt potrebbero non generare immagini corrispondenti: +- Contenuti violenti, erotici o inappropriati +- Contenuti che violano diritti d'immagine o copyright altrui +- Contenuti con informazioni politicamente sensibili + +### Consumo di Risorse +La generazione di immagini è un compito intensivo dal punto di vista computazionale e consuma molte risorse: +- Dimensioni più grandi consumano più risorse +- Abilitare la super risoluzione aumenta significativamente il consumo di risorse +- I modelli di alta qualità richiedono generalmente più tempo di elaborazione + +## ❓ Problemi Comuni + +### Immagine Generata Non Corrisponde alla Descrizione +**Problema**: Ho descritto un gatto, ma l'immagine generata non sembra un gatto. + +**Soluzioni**: +- Aumenta la specificità del prompt, ad es. "Un gatto arancione a pelo corto domestico con occhi verdi" +- Aggiungi più dettagli descrittivi come ambiente, posa, espressione +- Prova a usare parole di rinforzo come "alta qualità, ricco di dettagli" + +### Qualità dell'Immagine Scarsa +**Problema**: L'immagine generata è sfocata o ha difetti evidenti. + +**Soluzioni**: +- Abilita l'opzione "super risoluzione" +- Nel prompt negativo aggiungi "sfocato, rumore, deformato, bassa qualità" +- Prova a usare un modello di qualità superiore (come Flux1-Pro) +- Aumenta leggermente le dimensioni dell'immagine + +### Impossibile Generare Persone Specifiche o Marchi +**Problema**: Impossibile generare immagini di celebrità specifiche o marchi commerciali. + +**Soluzioni**: +- Questa è una limitazione di sicurezza del sistema per proteggere diritti d'immagine e proprietà intellettuale +- Prova a descrivere caratteristiche simili di una persona generica invece di celebrità specifiche +- Descrivi caratteristiche astratte del marchio invece di usare nomi di marchi specifici + +## 🔗 Nodi Comuni da Abbinare + +|Tipo di Nodo|Motivo dell'Abbinamento| +|---|---| +|Nodo Chiamata Modello Grande|Permette al modello grande di generare prompt appropriati basati sull'input utente, poi li passa al nodo generazione immagini| +|Nodo Ramo Condizionale|Seleziona diversi prompt o modelli basati su condizioni diverse| + +--- + # 图像生成节点 ## 什么是图像生成节点？ 图像生成节点是 Magic Flow 平台提供的一个强大工具，它能够根据您提供的文字描述（提示词）自动生成高质量的图像。就像是您在和一位专业画师沟通，通过描述您想要的画面，让画师为您绘制出相应的图片。 diff --git a/docs/zh/tutorial/basic/node/Intent-recognition.md b/docs/zh/tutorial/basic/node/Intent-recognition.md index 3211230ed..338733190 100644 --- a/docs/zh/tutorial/basic/node/Intent-recognition.md +++ b/docs/zh/tutorial/basic/node/Intent-recognition.md @@ -1,3 +1,146 @@ +# 🎯 Nodo Riconoscimento Intenzioni + +## ❓ Cos'è il Nodo Riconoscimento Intenzioni? + +Il nodo Riconoscimento Intenzioni è un nodo di analisi intelligente nei flussi di lavoro Magic Flow che può comprendere e analizzare il contenuto testuale dell'input dell'utente, identificando l'intenzione dell'utente al suo interno. In parole semplici, questo nodo è come un "interprete intelligente" che può distinguere cosa vuole fare l'utente, poi guida il flusso di lavoro verso percorsi di elaborazione diversi basati su intenzioni diverse. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Riconoscimento Intenzioni include l'area di selezione del modello e configurazione dei rami. Qui puoi definire molteplici rami di intenzione, ogni ramo contiene il nome dell'intenzione e la descrizione, oltre ai percorsi di flusso corrispondenti a diverse intenzioni. +![Nodo Riconoscimento Intenzioni](https://cdn.letsmagic.cn/static/img/Intent-recognition.png) + +## 🤔 Perché Serve il Nodo Riconoscimento Intenzioni? + +Nella costruzione di applicazioni intelligenti, il nodo Riconoscimento Intenzioni svolge un ruolo chiave di "navigazione intelligente": +- **Elaborazione Automatica di Classificazione**: Identifica automaticamente l'intenzione dell'utente basandosi sul suo input, senza bisogno che l'utente scelga esplicitamente la funzionalità +- **Design di Flussi Multi-percorso**: Attiva diversi flussi di elaborazione basati su intenzioni diverse, fornendo esperienze personalizzate +- **Miglioramento dell'Esperienza Utente**: Permette agli utenti di esprimere le proprie esigenze in linguaggio naturale, invece di seguire comandi fissi o menu +- **Riduzione del Giudizio Manuale**: Automatizza il processo di analisi delle intenzioni, risparmiando risorse umane +- **Semplificazione di Flussi Complessi**: Semplifica giudizi condizionali complessi in riconoscimento delle intenzioni basato sulla semantica + +## 🎯 Scenari Applicabili + +### 1. Smistamento Assistenza Clienti Intelligente +Progetta un sistema di assistenza clienti che può giudicare automaticamente il tipo di consultazione dell'utente, come consultazione prodotto, servizio post-vendita, reclami e suggerimenti, ecc., e guida l'utente verso i rispettivi flussi di elaborazione professionale. + +### 2. Assistente Multi-funzione +Costruisci un assistente personale integrato con molteplici funzionalità che può giudicare dall'input in linguaggio naturale dell'utente se vuole controllare il meteo, impostare promemoria, cercare informazioni o chiacchierare, ed eseguire la funzionalità corrispondente. + +### 3. Compilazione Intelligente Moduli +Crea un assistente moduli intelligente che può estrarre informazioni chiave dalle descrizioni in linguaggio naturale dell'utente e compilare automaticamente i campi del modulo corrispondenti, semplificando il processo di inserimento dati. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri Base +|Nome Parametro|Spiegazione|Obbligatorio|Valore Predefinito| +|---|---|---|---| +|Modello|Seleziona il modello di linguaggio grande da utilizzare per il riconoscimento delle intenzioni|Sì|gpt-4o-mini-global| +|Intenzione|Il contenuto dell'input dell'utente, utilizzato per l'analisi delle intenzioni|Sì|Nessuno| +|Rami Intenzione|Definisci diverse categorie di intenzione e i loro flussi di elaborazione|Sì|Nessuno| + +### Parametri Modello +|Nome Parametro|Spiegazione|Obbligatorio|Valore Predefinito| +|---|---|---|---| +|Caricamento Automatico Memoria|Se abilitare la funzione di memoria automatica, ricordare la cronologia delle conversazioni per assistere il riconoscimento delle intenzioni|No|Sì| +|Numero Massimo Memoria|Questo nodo ricorderà al massimo n messaggi, n è il numero massimo di memoria che imposti|No|10| + +### Parametri Intenzione +|Nome Parametro|Spiegazione|Obbligatorio| +|---|---|---| +|Nome Intenzione|Definisci un nome di intenzione specifico, come "consultazione prodotto", "richiesta rimborso", ecc.|Sì| +|Descrizione Intenzione|Descrizione dettagliata di questa intenzione, aiuta il modello a riconoscere più accuratamente l'intenzione|No| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Seleziona il modello appropriato**: + 1. Per garantire l'accuratezza del riconoscimento, si consiglia di scegliere modelli avanzati come GPT-4 + 2. Per compiti di riconoscimento intenzioni semplici, si possono anche utilizzare modelli più veloci come GPT-3.5 +2. **Imposta l'input dell'intenzione**: + 1. Nel parametro "Intenzione" fai riferimento al messaggio di input dell'utente, generalmente utilizzando variabili come `{{user_message}}` + 2. Assicurati che il contenuto di input contenga informazioni sufficienti per l'analisi delle intenzioni del modello +3. **Definisci i rami delle intenzioni**: + 1. Clicca il pulsante "Aggiungi Ramo" per creare molteplici rami di intenzione + 2. Imposta nomi di intenzione chiari e descrizioni dettagliate per ogni ramo + 3. Imposta almeno un ramo "else" di fallback per gestire situazioni non riconoscibili +4. **Configura la destinazione dei rami**: + 1. Imposta per ogni ramo di intenzione il nodo verso cui il flusso dovrebbe andare quando viene riconosciuta questa intenzione + 2. Assicurati che tutti i possibili percorsi di intenzione abbiano elaborazione corrispondente +5. **Regola parametri avanzati (opzionale)**: + 1. Regola parametri come temperatura, memoria automatica secondo necessità + 2. Per scenari che richiedono alta accuratezza, puoi impostare la temperatura più bassa (come 0.2) + +#### Collaborazione con Altri Nodi +Il nodo Riconoscimento Intenzioni generalmente necessita di essere utilizzato in combinazione con altri nodi: +1. **In Combinazione con il Nodo Attesa**: + 1. Dopo l'input dell'utente, utilizza il nodo Attesa per ottenere il messaggio + 2. Utilizza l'output del nodo Attesa come input per il riconoscimento delle intenzioni +2. **In Combinazione con il Nodo Chiamata Modello Grande**: + 1. Basandosi sull'intenzione riconosciuta, utilizza diversi template di prompt + 2. Puoi passare il risultato del riconoscimento delle intenzioni al modello grande per migliorare la comprensione del contesto +3. **Complementare al Nodo Ramo Condizionale**: + 1. Per giudizi con regole chiare utilizza il nodo Ramo Condizionale + 2. Per comprensione semantica fuzzy utilizza il nodo Riconoscimento Intenzioni + +## ⚠️ Note Importanti + +### Quantità e Qualità delle Intenzioni +La quantità di intenzioni influisce sulla precisione e efficienza del riconoscimento: +- Troppe intenzioni possono causare confusione e giudizi errati +- Si consiglia di controllare ogni nodo tra 5-10 intenzioni, assicurando distinzioni chiare tra le varie intenzioni +- Per sistemi complessi, considera l'utilizzo di riconoscimento intenzioni multi-livello, come riconoscere prima la categoria principale, poi la sottocategoria + +### Impostazione Ramo Predefinito +Assicurati sempre di impostare un ramo predefinito di tipo "else": +- Come percorso di fallback quando non viene riconosciuta alcuna intenzione predefinita +- Può guidare l'utente a chiarire l'intenzione o fornire più informazioni +- Previene l'interruzione del flusso a causa dell'impossibilità di riconoscere l'intenzione + +### Considerazioni sulle Performance +Il processo di riconoscimento delle intenzioni può consumare una certa quantità di risorse computazionali: +- Sistemi di intenzioni complessi possono aumentare il tempo di riconoscimento +- Per scenari con requisiti di real-time elevati, puoi semplificare leggermente le descrizioni delle intenzioni +- Considera l'utilizzo di modelli più veloci o ottimizzazione della struttura dei prompt + +## ❓ Problemi Comuni + +### Problema 1: Come Migliorare l'Accuratezza del Riconoscimento delle Intenzioni? +**Soluzioni**: Diversi fattori chiave per migliorare l'accuratezza: +- Fornire descrizioni dettagliate delle intenzioni ed esempi diversificati +- Assicurare sufficiente distinzione tra diverse intenzioni +- Utilizzare modelli più avanzati (come GPT-4 al posto di GPT-3.5) +- Abbassare il parametro temperatura (come 0.2-0.3) per aumentare la determinabilità +- Considerare l'abilitazione della funzione memoria per utilizzare la cronologia delle conversazioni come contesto + +### Problema 2: Il Riconoscimento delle Intenzioni Va Sempre Verso il Ramo Predefinito? +**Soluzioni**: Possibili cause e soluzioni: +- Verifica se le descrizioni delle intenzioni sono sufficientemente chiare e dettagliate +- Conferma se l'input dell'utente contiene informazioni sufficienti per indicare l'intenzione +- Controlla se ci sono sovrapposizioni tra intenzioni che causano confusione +- Prova ad aggiungere alcune espressioni comuni nelle descrizioni delle intenzioni +- Utilizza la funzione di debug per visualizzare il processo di riconoscimento del modello e la confidenza + +### Problema 3: Come Gestire Situazioni di Intenzioni Multiple? +**Soluzioni**: Quando l'input dell'utente può contenere molteplici intenzioni: +- Progetta priorità dei rami, lascia che il modello riconosca l'intenzione principale +- Considera l'impostazione di rami di intenzione ibrida per gestire combinazioni di intenzioni comuni +- Aggiungi passi di chiarimento nel flusso, chiedi all'utente di confermare l'intenzione principale +- Utilizza elaborazione a catena: prima elabora l'intenzione principale, poi quella secondaria + +## 💡 Migliori Pratiche + +### Nodi Comuni da Abbinare + +|Tipo di Nodo|Motivo dell'Abbinamento| +|---|---| +|Nodo Attesa|Ottieni l'input dell'utente come fonte per il riconoscimento delle intenzioni| +|Nodo Chiamata Modello Grande|Genera risposte corrispondenti basandosi sull'intenzione riconosciuta| +|Nodo Ramo Condizionale|Gestisci giudizi semplici basati su regole| +|Nodo Risposta Messaggio|Feedback all'utente del risultato del riconoscimento o richiesta di chiarimento| +|Nodo Sottoprocesso|Esegui flussi di elaborazione indipendenti per ciascuna intenzione| + +--- + # 意图识别节点 ## 什么是意图识别节点？ 意图识别节点是Magic Flow工作流中的智能分析节点，它能够理解和分析用户输入的文本内容，从中识别出用户的意图。简单来说，这个节点就像是一个"理解师"，能够分辨用户想要做什么，然后根据不同意图将工作流引导到不同的处理路径。 diff --git a/docs/zh/tutorial/basic/node/Knowledge-retrieval.md b/docs/zh/tutorial/basic/node/Knowledge-retrieval.md index 567a42b9b..09ceba266 100644 --- a/docs/zh/tutorial/basic/node/Knowledge-retrieval.md +++ b/docs/zh/tutorial/basic/node/Knowledge-retrieval.md @@ -1,3 +1,142 @@ +# 🔍 Nodo Recupero Conoscenza + +## ❓ Cosa è il Nodo Recupero Conoscenza? + +Il nodo recupero conoscenza è uno strumento potente di ricerca semantica, capace di cercare contenuti rilevanti nella knowledge base Magic specificata basandosi sulle parole chiave inserite dall'utente. Questo nodo utilizza la tecnologia di matching di similarità vettoriale per aiutare a localizzare rapidamente i frammenti di conoscenza necessari, realizzando un recupero e un'applicazione efficiente della conoscenza. + +**Spiegazione Immagine:** + +L'interfaccia del nodo recupero conoscenza include principalmente l'area di selezione knowledge base, l'area di impostazione parametri di ricerca e l'area di configurazione output. È possibile selezionare la fonte della knowledge base al centro e impostare parametri come soglia di similarità, numero massimo, ecc. +![Nodo Recupero Conoscenza](https://cdn.letsmagic.cn/static/img/Knowledge-retrieval-node.png) + +## 🎯 Perché Serve il Nodo Recupero Conoscenza? +Nel processo di costruzione di applicazioni intelligenti, il nodo recupero conoscenza risolve i seguenti problemi chiave: +- **Acquisizione Conoscenza Professionale**: Permettere all'AI di ottenere e utilizzare documenti, materiali o conoscenze professionali interne all'azienda +- **Migliorare Accuratezza Risposte**: Attraverso il recupero di informazioni rilevanti, rendere le risposte AI più accurate e professionali, ridurre risposte "immaginate" o obsolete +- **Aggiornabilità Conoscenze**: È possibile ottenere contenuti di conoscenza aggiornati, risolvere la limitazione della data di cutoff delle conoscenze dei modelli grandi +- **Contenuti Personalizzati**: Fornire risposte di conoscenza mirate in base alle esigenze specifiche dell'utente +- **Ridurre Costi Addestramento**: Non è necessario riaddestrare il modello per ogni nuova conoscenza, basta aggiornare la knowledge base + +## 📋 Scenari Applicabili +### 1. 🏢 Sistema Domande e Risposte Interne Aziendali +Costruire un assistente capace di rispondere a domande su policy aziendali, processi, informazioni prodotto, ecc., aiutare i nuovi dipendenti a comprendere rapidamente le informazioni aziendali o assistere i dipendenti esperti nella consultazione delle ultime disposizioni. +### 2. 🤖 Robot Assistente Clienti Professionale +Creare un robot assistente clienti capace di rispondere con precisione a domande su prodotti, risoluzione problemi, guide d'uso, ecc., migliorare la qualità e l'efficienza del servizio clienti. +### 3. 📄 Assistente Intelligente Documenti +Progettare un assistente intelligente capace di comprendere e rispondere a contenuti di documenti specifici, come interpretazione manuali prodotto, spiegazione termini contrattuali, analisi rapporti di ricerca, ecc. +### 4. 🎓 Sistema Tutoraggio Didattico +Costruire un sistema di tutoraggio capace di rispondere a domande di apprendimento basate su materiali didattici, fornire spiegazioni di conoscenza, aiutare gli studenti a comprendere meglio concetti complessi. + +## ⚙️ Spiegazione Parametri Nodo +### Parametri Base +|Nome Parametro|Spiegazione|Obbligatorio|Valore Default| +|---|---|---|---| +|Knowledge Base|Selezionare la knowledge base da ricercare, è possibile scegliere una o più|Sì|Nessuna| +|Parole Chiave Ricerca|Parole chiave o domanda per la ricerca, utilizzate per trovare contenuti rilevanti|Sì|Nessuna| +|Similarità Minima|Impostare il requisito di similarità minima per il matching della conoscenza, range 0~1|-|0.4| +|Numero Massimo Richiami|Numero massimo di risultati da restituire|-|5| + +### Parametri Avanzati +### Contenuto Output +|Campo Output|Spiegazione| +|---|---| +|Lista Frammenti (fragments)|Lista dei frammenti di conoscenza recuperati, contenenti contenuto e informazioni di similarità| +|Set Risultati Richiamati (similarities)|Lista dei punteggi di similarità di ciascun frammento| +|total_count|Quantità totale di frammenti di conoscenza recuperati| + +## 📖 Istruzioni per l'Uso +### Passi di Configurazione Base +1. **Selezionare Knowledge Base**： + 1. Cliccare sul menu a tendina della knowledge base, selezionare una o più knowledge base da ricercare + 2. È possibile scegliere knowledge base pubbliche o knowledge base dedicate create autonomamente +2. **Impostare Parole Chiave Ricerca**： + 1. Inserire le parole chiave o la domanda per la ricerca + 2. È possibile inserire direttamente testo fisso, come "Qual è la policy aziendale per le ferie annuali?" + 3. È anche possibile utilizzare riferimento variabili per contenuti dinamici, come `user_question}}` per fare riferimento alla domanda effettiva dell'utente +3. **Regolare Similarità Minima**： + 1. Trascinare il cursore per impostare la soglia di similarità (tra 0.01 e 0.99) + 2. Valore più alto richiede matching più preciso, ma potrebbe perdere contenuti rilevanti + 3. Valore più basso include più contenuti rilevanti, ma potrebbe mostrare risultati non molto correlati +4. **Impostare Numero Massimo Richiami**： + 1. Impostare il numero massimo di risultati da restituire in base alle esigenze + 2. Si consiglia 3-5 elementi, per fornire informazioni sufficienti senza eccedere + +### Tecniche Avanzate +#### Ottimizzazione Effetto Ricerca +1. **Migliorare Precisione Ricerca**： + 1. Utilizzare domande chiare e specifiche piuttosto che parole chiave generiche + 2. Aumentare la soglia di similarità (come 0.7 o superiore) per ottenere matching più precisi + 3. Selezionare knowledge base specializzate per temi specifici piuttosto che knowledge base generali +2. **Aumentare Copertura Ricerca**： + 1. Utilizzare molteplici knowledge base correlate contemporaneamente + 2. Abbassare appropriatamente la soglia di similarità (come 0.5 circa) + 3. Aumentare il numero massimo di restituzioni + +#### Collaborazione con Altri Nodi +1. **In Combinazione con Nodo Chiamata Modello Grande**： + 1. Fornire i risultati di ricerca come contesto al modello grande + 2. Permettere al modello grande di generare risposte più accurate basate sulla conoscenza recuperata +2. **In Combinazione con Nodo Ramo Condizionale**： + 1. Verificare se sono stati trovati contenuti rilevanti (lunghezza fragments > 0) + 2. Se ci sono risultati, fornire risposta professionale + 3. Se non ci sono risultati, passare a risposta generica o servizio umano +3. **In Combinazione con Nodo Salvataggio Variabili**： + 1. Salvare i risultati di ricerca per l'utilizzo in molteplici nodi successivi + 2. Evitare ricerche ripetute dello stesso contenuto, migliorare l'efficienza + +## ⚠️ Note di Attenzione +### Qualità Knowledge Base +L'effetto del recupero conoscenza dipende in larga misura dalla qualità della knowledge base: +- Assicurarsi che i contenuti della knowledge base siano accurati, completi e aggiornati +- Aggiornare regolarmente la knowledge base, eliminare informazioni obsolete +- Classificare e taggare appropriatamente i contenuti di conoscenza, migliorare la precisione di ricerca + +### Efficienza Ricerca +La ricerca in knowledge base di grandi dimensioni potrebbe influenzare le performance: +- Cercare di selezionare la knowledge base più correlata alla domanda, piuttosto che ricercare in tutte le knowledge base +- Impostare ragionevolmente il numero massimo, evitare di restituire troppi risultati non necessari +- Considerare di mettere in cache i risultati di ricerca per domande comuni, migliorare la velocità di risposta + +### Privacy e Sicurezza +La knowledge base potrebbe contenere informazioni sensibili: +- Assicurarsi che le impostazioni dei permessi di accesso alla knowledge base siano corrette +- Evitare di esporre contenuti di conoscenza sensibili in scenari pubblici +- Applicare filtri di contenuto necessari ai risultati di ricerca + +## ❓ Domande Frequenti +### Domanda 1: Cosa fare se non si riescono a recuperare contenuti rilevanti? +**Soluzioni**： +- Provare ad abbassare la soglia di similarità, ad esempio da 0.7 a 0.5 +- Riorganizzare la domanda di ricerca, utilizzare più parole chiave o espressioni più concise +- Verificare se la knowledge base contiene contenuti correlati, aggiornare la knowledge base se necessario +- Considerare di selezionare più knowledge base correlate per la ricerca + +### Domanda 2: Cosa fare se i risultati di ricerca includono troppi contenuti non rilevanti? +**Soluzioni**： +- Aumentare la soglia di similarità, ad esempio da 0.5 a 0.7 o superiore +- Utilizzare descrizioni di domanda più precise +- Restringere l'ambito della knowledge base, selezionare knowledge base più focalizzate su temi specifici +- Ridurre il numero massimo di restituzioni + +### Domanda 3: Come gestire domande diversificate degli utenti? +**Soluzioni**： +- Utilizzare il nodo riconoscimento intento per analizzare prima il tipo di domanda dell'utente +- Selezionare knowledge base diverse in base a tipi di domanda differenti +- Configurare soglie di similarità e numeri massimi diversi +- Combinare con il modello grande per integrare e ottimizzare i risultati di ricerca + +## 🌟 Migliori Pratiche +### Nodi di Combinazione Comuni +|Tipo di Nodo|Motivo di Combinazione| +|---|---| +|Nodo Chiamata Modello Grande|Fornire i risultati di ricerca come contesto al modello grande, generare risposte basate sulla conoscenza| +|Nodo Ramo Condizionale|Decidere il flusso di elaborazione successivo in base ai risultati di ricerca| +|Nodo Risposta Messaggio|Rispondere i contenuti di conoscenza elaborati all'utente| +|Nodo Segmentazione Testo|Elaborare risultati di ricerca troppo lunghi, assicurarsi che siano adatti per l'elaborazione successiva| +|Nodo Salvataggio Variabili|Salvare i risultati di ricerca per l'utilizzo in molteplici nodi| + +--- + # 知识检索节点 ## 什么是知识检索节点？ diff --git a/docs/zh/tutorial/basic/node/Large-model.md b/docs/zh/tutorial/basic/node/Large-model.md index 6bdee4f55..af84d026a 100644 --- a/docs/zh/tutorial/basic/node/Large-model.md +++ b/docs/zh/tutorial/basic/node/Large-model.md @@ -1,3 +1,142 @@ +# 🧠 Nodo di Chiamata Modello Grande +## ❓ Cosa è il Nodo di Chiamata Modello Grande? +Il nodo di chiamata modello grande è il nodo core nel flusso di lavoro Magic Flow, permette di interagire direttamente con modelli di linguaggio di grandi dimensioni (come GPT-4, ecc.), utilizzato per generare contenuti testuali, rispondere a domande, analizzare contenuti o effettuare ragionamenti. In parole semplici, questo nodo è come un ponte per dialogare con l'intelligenza artificiale sulla piattaforma Magic. + +**Spiegazione Immagine:** + +L'interfaccia del nodo di chiamata modello grande include aree di configurazione core come selezione modello, prompt di sistema, prompt utente, e opzioni di configurazione avanzate come regolazione parametri modello, configurazione knowledge base, ecc. +![Nodo Modello Grande](https://cdn.letsmagic.cn/static/img/Large-model.png) + +## 🎯 Perché Serve il Nodo di Chiamata Modello Grande? +Nel processo di costruzione di applicazioni intelligenti, il nodo di chiamata modello grande svolge il ruolo di "cervello", fornendo capacità di decisione intelligente e generazione contenuti per il flusso di lavoro: +- **Elaborazione Linguaggio Naturale**: Comprensione e generazione di linguaggio umano, permettendo all'applicazione di comunicare con gli utenti in modo naturale +- **Creazione Contenuti**: Generazione di copy, riassunti, traduzioni o altri contenuti creativi +- **Domande e Risposte Conoscenza**: Risposta a domande in campi professionali basate sulla knowledge base configurata +- **Ragionamento Logico**: Analisi informazioni e raggiungimento conclusioni, assistenza nella formulazione decisioni +- **Interazione Personalizzata**: Fornitura risposte personalizzate basate sulle esigenze utente e storico + +## 📋 Scenari Applicabili +### 1. 🤖 Robot Assistente Clienti Intelligente +Progettare un robot assistente clienti capace di rispondere a consulenze prodotto, risolvere problemi utente, attraverso configurazione knowledge base professionale, fornire informazioni accurate sui prodotti e soluzioni. +### 2. ✍️ Assistente Creazione Contenuti +Costruire un assistente capace di generare vari tipi di copy, riassunti o contenuti creativi, come copy marketing, descrizioni prodotto o post social media. +### 3. 📚 Sistema Domande e Risposte Knowledge Base +Creare un sistema di domande e risposte basato su documenti interni aziendali, permettendo ai dipendenti di ottenere rapidamente informazioni professionali, migliorando l'efficienza lavorativa. +### 4. 📊 Analisi e Interpretazione Dati +Convertire risultati di analisi dati in spiegazioni di linguaggio naturale facilmente comprensibili, aiutando il personale non tecnico a comprendere dati complessi. + +## ⚙️ Spiegazione Parametri Nodo +### Parametri Base +|Nome Parametro|Spiegazione|Obbligatorio|Valore Default| +|---|---|---|---| +|Modello|Selezione del modello di linguaggio da utilizzare, come GPT-4, Claude, ecc.|Sì|gpt-4o-global| +|Strumenti|Configurazione capacità strumenti associati, permettere al modello di rispondere basandosi su conoscenze specifiche||| +|Impostazione Knowledge Base|Configurazione knowledge base associata, permettere al modello di rispondere basandosi su conoscenze specifiche|No|Nessuna| +|Prompt Sistema|Istruzioni di background per il modello, definizione ruolo e comportamento generale del modello|Sì|Nessuno| +|Prompt Utente|Domanda specifica o istruzioni dell'utente|No|Nessuno| + +### Configurazione Modello +|Nome Parametro|Spiegazione|Obbligatorio|Valore Default| +|---|---|---|---| +|Temperatura|Controllo casualità output, valore maggiore risposta più creativa, valore minore risposta più deterministica|No|0.5| +|Caricamento Automatico Memoria|Se abilitare funzione memoria automatica, ricordare storico conversazione|No|Sì| +|Numero Massimo Memoria|Quantità massima messaggi storici da ricordare|No|50| +|Modello Comprensione Visiva|Nome modello grande per elaborazione immagini|No|Nessuno| +|Messaggi Storici|Impostazione messaggi conversazione storica, per costruire contesto dialogo|No|Nessuno| + +### Contenuto Output +|Campo Output|Spiegazione| +|---|---| +|Risposta Modello Grande (response)|Contenuto risposta del modello grande, utilizzabile per mostrare all'utente o passare a nodi downstream| +|Strumenti Chiamati (tool_calls)|Informazioni strumenti chiamati dal modello, contenenti nome strumento, parametri, risultati, ecc.| + +## 📖 Istruzioni per l'Uso +### Passi di Configurazione Base +1. **Selezionare il Modello Appropriato**： + 1. Selezionare il modello di linguaggio grande corrispondente in base alle esigenze + 2. Per compiti generali è possibile selezionare modelli ordinari, per compiti complessi selezionare modelli avanzati come GPT-4 +2. **Scrivere il Prompt di Sistema**： + 1. Definire chiaramente il ruolo del modello, come "Sei un addetto al servizio clienti" + 2. Impostare lo stile e l'ambito delle risposte + 3. Informare il modello sulle risorse o strumenti utilizzabili +3. **Configurare il Prompt Utente**： + 1. È possibile inserire direttamente domande o istruzioni fisse + 2. È anche possibile utilizzare riferimenti variabili per contenuti dinamici, come `{{user_message}}` per fare riferimento all'input effettivo dell'utente +4. **Impostare i Parametri del Modello**： + 1. Regolare la temperatura per controllare la creatività o accuratezza delle risposte + 2. Impostare se abilitare la memoria automatica e la quantità di record storici +5. **Configurare la Knowledge Base (Opzionale)**： + 1. Selezionare la knowledge base da associare + 2. Impostare la soglia di similarità e il numero di risultati di ricerca + +### Tecniche Avanzate +#### Ottimizzazione Prompt +Scrivere prompt di alta qualità è la chiave per utilizzare efficacemente i modelli grandi： +1. **Essere Specifico e Chiaro**：Esprimere chiaramente le proprie aspettative e esigenze +2. **Impostazione Ruolo**：Assegnare al modello una posizione di ruolo chiara nel prompt di sistema +3. **Suddivisione Passi**：Guidare il modello a pensare per passi su problemi complessi + +#### Collaborazione con Altri Nodi +1. **In Combinazione con il Nodo Risposta Messaggio**： + 1. Mostrare all'utente l'output generato dal modello grande attraverso il nodo risposta messaggio + 2. Impostare il prompt utente come vuoto, permettendo al messaggio dell'utente di diventare automaticamente l'input +2. **In Combinazione con il Nodo Ramo Condizionale**： + 1. Utilizzare il nodo riconoscimento intento per analizzare l'intento dell'utente + 2. Dirigere verso diversi flussi di elaborazione in base a diversi intenti +3. **In Combinazione con il Nodo Recupero Conoscenza**： + 1. Utilizzare prima il nodo recupero conoscenza per ottenere informazioni rilevanti + 2. Fornire poi i risultati della ricerca come contesto al modello grande + +## ⚠️ Note di Attenzione +### Limitazioni Token +Ogni modello ha un limite massimo di token elaborabili, superarlo causerà errori： +- GPT-3.5：Supporta al massimo 16K tokens +- GPT-4：Supporta al massimo 128K tokens +- Claude：Supporta al massimo 200K tokens + +*Suggerimento：Circa 1 carattere cinese ≈ 1.5-2 tokens, 1 parola inglese ≈ 1-2 tokens* + +### Aggiornabilità delle Conoscenze +Le conoscenze dei modelli grandi hanno una data di cutoff dell'addestramento, potrebbero non conoscere le informazioni più recenti, si consiglia： +- Per scenari che richiedono informazioni aggiornate, considerare l'utilizzo combinato del nodo richiesta HTTP per ottenere dati in tempo reale +- O aggiornare regolarmente le ultime informazioni attraverso la knowledge base + +### Gestione Informazioni Sensibili +I modelli grandi potrebbero elaborare informazioni fornite dagli utenti, prestare attenzione： +- Evitare di includere informazioni riservate o sensibili nei prompt +- Per dati che necessitano di riservatezza, si consiglia di utilizzare la knowledge base invece dell'input diretto + +## ❓ Domande Frequenti +### Domanda 1: Cosa fare se il contenuto della risposta del modello grande non corrisponde alle aspettative? +**Soluzioni**：Potrebbe essere che il prompt non sia abbastanza chiaro. Provare： +- Modificare il prompt di sistema, definire più specificamente il compito e le aspettative +- Aggiungere esempi, mostrare la modalità di domanda e risposta ideale +- Regolare il parametro temperatura, abbassare la temperatura per rendere la risposta più deterministica + +### Domanda 2: Come gestire domande professionali che il modello grande non riesce a rispondere? +**Soluzioni**：Il modello grande dipende dai dati di addestramento, potrebbe avere conoscenze limitate in campi specifici： +- Configurare una knowledge base professionale, fornire supporto di conoscenze di settore +- Aggiungere conoscenze di background necessarie nel prompt di sistema +- Utilizzare l'istruzione "se non si trova informazione, informare chiaramente" per evitare di inventare risposte + +### Domanda 3: Cosa fare se l'esecuzione del nodo chiamata modello grande è lenta? +**Soluzioni**：I fattori che influenzano la velocità sono molteplici： +- Provare a utilizzare modelli con risposta più veloce (come GPT-3.5 al posto di GPT-4) +- Ridurre la quantità di messaggi storici, diminuire il carico di elaborazione +- Ottimizzare il prompt, renderlo più conciso e chiaro + +## 🌟 Migliori Pratiche +### Nodi di Combinazione Comuni +|Tipo di Nodo|Motivo di Combinazione| +|---|---| +|Nodo Risposta Messaggio|Inviare all'utente il contenuto generato dal modello grande| +|Nodo Ramo Condizionale|Decidere l'operazione successiva in base all'output del modello grande| +|Nodo Recupero Conoscenza|Fornire supporto di conoscenze professionali| +|Nodo Query Messaggi Storici|Fornire contesto di conversazione, migliorare la coerenza| +|Nodo Salvataggio Variabili|Salvare informazioni importanti per l'utilizzo nei flussi successivi| + +--- + # 大模型调用节点 ## 什么是大模型调用节点？ 大模型调用节点是Magic Flow工作流中的核心节点，它允许您直接与大型语言模型（如GPT-4等）进行交互，用于生成文本内容、回答问题、分析内容或进行推理。简单来说，这个节点就像是您在Magic平台上与人工智能对话的桥梁。 @@ -28,7 +167,7 @@ |参数名称|说明|是否必填|默认值| |---|---|---|---| |模型|选择要使用的大语言模型，如GPT-4、Claude等|是|gpt-4o-global| -|工具|配置关联的工具能力，让模型基于特定知识回答||| +|工具|配置关联的工具能力，让模型基于特定知识回答||| |知识库设置|配置关联的知识库，让模型基于特定知识回答|否|无| |系统提示词|给模型的背景指令，定义模型的角色和整体行为|是|无| |用户提示词|用户的具体问题或指令|否|无| diff --git a/docs/zh/tutorial/basic/node/Loop.md b/docs/zh/tutorial/basic/node/Loop.md index 2d50ecf2d..7b13f6b7f 100644 --- a/docs/zh/tutorial/basic/node/Loop.md +++ b/docs/zh/tutorial/basic/node/Loop.md @@ -1,3 +1,131 @@ +# 🔄 Nodo Ciclo + +## ❓ Cos'è il Nodo Ciclo? + +Il nodo Ciclo è un tipo di nodo di controllo del flusso nei flussi di lavoro Magic Flow che permette di ripetere l'esecuzione di una serie di operazioni fino a quando non viene soddisfatta una condizione specifica o completato un numero designato di volte. In parole semplici, il nodo Ciclo è come un'istruzione "ripeti esecuzione" che aiuta ad automatizzare compiti ripetitivi, migliorando l'efficienza lavorativa. + +**Spiegazione Immagine:** +L'interfaccia del nodo Ciclo include due parti principali: il componente "Ciclo" esterno e il "Nodo Inizio" interno. Nel componente Ciclo, puoi impostare il tipo di ciclo, le condizioni di ciclo o il numero di volte; il nodo Inizio rappresenta invece il punto di partenza per ogni esecuzione del ciclo. +![Nodo Ciclo](https://cdn.letsmagic.cn/static/img/Loop.png) + +## 🤔 Perché Serve il Nodo Ciclo? + +Nella costruzione di applicazioni intelligenti, il nodo Ciclo risolve il problema dell'esecuzione ripetuta di alcune operazioni, ed è in grado di: +- **Elaborazione Dati in Batch**: Eseguire la stessa operazione su ogni elemento di una lista o array +- **Tentativi Ripetuti**: Continuare l'esecuzione di un compito fino a quando non viene soddisfatta una condizione specifica +- **Esecuzione Programmata**: Ripetere l'esecuzione di compiti secondo un numero fisso di volte +- **Flussi di Lavoro Dinamici**: Decidere flessibilmente il numero di esecuzioni secondo la situazione effettiva +- **Risparmio di Lavoro**: Evitare la copia manuale e incolla di sequenze di nodi identiche + +## 🎯 Scenari Applicabili + +### 1. Elaborazione Dati in Batch +Elaborare un gruppo di dati, come scorrere una lista clienti per inviare messaggi personalizzati, o elaborare ogni riga di dati in una tabella. + +### 2. Meccanismo di Retry +Effettuare retry quando alcune operazioni falliscono, fino al successo o al raggiungimento del numero massimo di tentativi. + +### 3. Richieste Paginazione +Quando è necessario chiamare più volte un'API per ottenere dati paginati, controllare il numero di richieste e la variazione dei parametri attraverso il ciclo. + +### 4. Controlli Programmati +Ripetere controlli di uno stato secondo il numero impostato o le condizioni, come controllare periodicamente lo stato di completamento di un compito. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri Base +|Nome Parametro|Tipo Parametro|Obbligatorio|Descrizione| +|---|---|---|---| +|Tipo Ciclo|Selezione Dropdown|Sì|Scegli il tipo di ciclo, include "Ciclo Conteggio", "Ciclo Array" e "Ciclo Condizionale"| +|Numero Cicli|Numero/Variabile|A seconda del tipo|Quando si sceglie "Ciclo Conteggio", imposta il numero totale di esecuzioni del ciclo| +|Array Ciclo|Variabile|A seconda del tipo|Quando si sceglie "Ciclo Array", specifica l'array o lista da scorrere| +|Ciclo Condizionale|Espressione|A seconda del tipo|Quando si sceglie "Ciclo Condizionale", imposta l'espressione di condizione per continuare il ciclo| +|Nome Variabile Indice Corrente|Testo|No|Utilizzato per memorizzare il nome della variabile dell'indice corrente del ciclo, predefinito "loopIndex"| +|Nome Variabile Elemento Corrente|Testo|No|Utilizzato per memorizzare il nome della variabile dell'elemento corrente del ciclo, predefinito "loopItem"| +|Numero Massimo Cicli|Numero|No|Limitazione di sicurezza per prevenire cicli infiniti, imposta il numero massimo di cicli eseguibili| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Seleziona il tipo di ciclo**: + 1. Per numero: Adatto per situazioni in cui si conosce il numero esatto di esecuzioni + 2. Scorrimento array: Adatto per situazioni in cui è necessario elaborare ogni elemento dell'array + 3. Giudizio condizionale: Adatto per situazioni in cui è necessario fermarsi quando viene soddisfatta una condizione specifica +2. **Configura i parametri del ciclo**: + 1. Per numero: Imposta il numero specifico di cicli, come "10" + 2. Scorrimento array: Seleziona o inserisci la variabile array da scorrere + 3. Giudizio condizionale: Imposta l'espressione di condizione del ciclo e il numero massimo di cicli +3. **Configura il corpo del ciclo**: + 1. Aggiungi all'interno del nodo Ciclo i nodi che necessitano di esecuzione ripetuta + 2. Questi nodi verranno ripetuti secondo le impostazioni del ciclo +4. **Gestisci i risultati del ciclo**: + 1. Puoi utilizzare il nodo Salvataggio Variabili all'interno del ciclo per salvare risultati intermedi + 2. Dopo la fine del ciclo, queste variabili possono essere utilizzate dai nodi successivi + +## ⚠️ Note Importanti + +### Considerazioni sulle Performance +Il nodo Ciclo può causare un prolungamento del tempo di esecuzione del flusso di lavoro: +- Cerca di evitare di impostare numeri di cicli troppo grandi +- Per grandi quantità di dati, considera l'elaborazione in batch +- Per i cicli condizionali è necessario impostare un numero massimo di cicli ragionevole per prevenire cicli infiniti + +### Ambito delle Variabili nel Ciclo +Le variabili modificate nel ciclo influenzeranno i cicli successivi: +- Se necessiti di variabili indipendenti per ogni ciclo, reinizializzale all'inizio del ciclo +- Le modifiche delle variabili all'interno del ciclo verranno mantenute fino alla fine del ciclo + +### Limitazioni dei Cicli Annidati +Anche se tecnicamente supporta cicli annidati, presta attenzione: +- I cicli annidati aumenteranno significativamente la complessità e il tempo di esecuzione +- Si consiglia di non superare 2 livelli di annidamento per mantenere la manutenibilità del flusso di lavoro +- Nei cicli annidati presta particolare attenzione all'impostazione di numeri di cicli ragionevoli + +## ❓ Problemi Comuni + +### Problema 1: Il Numero di Esecuzioni del Nodo Ciclo Supera le Aspettative? +**Soluzioni**: Potrebbe essere dovuto a impostazioni errate delle condizioni del ciclo. Si consiglia: +- Verifica se le condizioni del ciclo sono impostate correttamente +- Assicurati di aggiornare le variabili di giudizio delle condizioni al momento opportuno +- Utilizza il nodo Esecuzione Codice per impostare manualmente un flag di interruzione per terminare anticipatamente il ciclo + +### Problema 2: I Nodi all'Interno del Ciclo Non Vengono Eseguiti Come Previsto? +**Soluzioni**: Questo potrebbe avere diverse cause: +- Assicurati che i nodi all'interno del corpo del ciclo siano connessi correttamente +- Verifica se i giudizi condizionali di ogni nodo sono corretti +- Utilizza il nodo Salvataggio Variabili per salvare risultati intermedi, facilitando il debug +- Verifica se le variabili utilizzate nel ciclo sono inizializzate correttamente + +### Problema 3: Come Salvare i Risultati di Ogni Iterazione nel Ciclo? +**Soluzioni**: Puoi: +- Utilizzare variabili array per raccogliere i risultati di ogni ciclo +- Nel nodo Esecuzione Codice aggiungere i risultati all'array +- Dopo la fine del ciclo, l'array conterrà tutti i risultati delle iterazioni + +```javascript +// Inizializza array risultati (prima del ciclo) +context.variableSave("results", []); + +// Nel ciclo salva ogni risultato +let results = context.variableGet("results", []); +results.push(someResult); +context.variableSave("results", results); +``` + +## 💡 Migliori Pratiche + +### Nodi Comuni da Abbinare + +|Tipo di Nodo|Motivo dell'Abbinamento| +|---|---| +|Nodo Esecuzione Codice|Gestisce logica complessa nel ciclo, opera su array e oggetti| +|Nodo Ramo Condizionale|Esegue diverse operazioni nel ciclo basate su condizioni| +|Nodo Salvataggio Variabili|Memorizza risultati intermedi o valori cumulativi nel ciclo| +|Nodo Richiesta HTTP|Invia richieste in batch o ottiene dati paginati| +|Nodo Memorizzazione Dati|Salva i risultati dell'elaborazione del ciclo in memoria persistente| + +--- + # 循环节点 ## 什么是循环节点？ 循环节点是Magic Flow工作流中的一种流程控制节点，它允许您重复执行一系列操作，直到满足特定的条件或完成指定的次数。简单来说，循环节点就像是一个"重复执行"的指令，帮助您自动化重复性任务，提高工作效率。 diff --git a/docs/zh/tutorial/basic/node/Personnel-retrieval.md b/docs/zh/tutorial/basic/node/Personnel-retrieval.md index fbe5af3c2..757b5b566 100644 --- a/docs/zh/tutorial/basic/node/Personnel-retrieval.md +++ b/docs/zh/tutorial/basic/node/Personnel-retrieval.md @@ -1,3 +1,142 @@ +# 👥 Nodo Recupero Personale + +## ❓ Cos'è il Nodo Recupero Personale? + +Il nodo Recupero Personale è un nodo funzionale specializzato nei flussi di lavoro Magic Flow per interrogare e filtrare le informazioni del personale organizzativo. Permette di localizzare e ottenere rapidamente dati del personale basati su molteplici condizioni (come nome, numero dipendente, posizione, dipartimento, ecc.), proprio come effettuare una ricerca precisa nella rubrica aziendale. + +**Spiegazione Interfaccia:** + +L'interfaccia del nodo Recupero Personale è composta principalmente dall'area di impostazione delle condizioni di ricerca e dall'area di anteprima della struttura dei dati di output. In alto vengono mostrati vari opzioni di configurazione delle condizioni di filtro, inclusi condizioni di filtro come nome utente, numero dipendente, posizione, ecc.; in basso viene mostrata la struttura dei dati dei risultati della query, inclusi campi di informazioni di base dell'utente e informazioni del dipartimento. +![Nodo Recupero Personale](https://cdn.letsmagic.cn/static/img/Personnel-retrieval.png) + +## 🤔 Perché Serve il Nodo Recupero Personale? + +Nel flusso di lavoro aziendale, ottenere accuratamente le informazioni del personale è una esigenza di base per molti processi di automazione: +- **Associazione Dati**: Associare i dati aziendali con responsabili specifici o team +- **Controllo Permessi**: Dividere i permessi di accesso alle informazioni secondo il ruolo o dipartimento del personale +- **Flusso del Processo**: Identificare la persona che gestisce o approva il passo successivo del processo +- **Notifiche Messaggi**: Inviare notifiche automatiche a personale specifico o team +- **Collaborazione Team**: Costruire processi di collaborazione intelligente basati sulla struttura organizzativa + +## 🎯 Scenari Applicabili + +### 1. Processo di Approvazione Intelligente +Basandosi sul contenuto della richiesta, trovare automaticamente la persona di approvazione del dipartimento corrispondente, inoltrare con precisione la richiesta di approvazione, migliorare l'efficienza del processo. + +### 2. Riepilogo Informazioni Dipartimentali +Recuperare rapidamente le informazioni di tutti i membri di un dipartimento specifico, utilizzato per generare report dipartimentali, analisi team o allocazione risorse. + +### 3. Collegamento Dati Personale +Quando l'utente presenta una richiesta, associare automaticamente informazioni come il suo dipartimento, superiore diretto, ecc. basandosi sulla sua identità, riducendo l'input manuale. + +### 4. Distribuzione Messaggi Intelligente +Trovare automaticamente i responsabili correlati secondo le regole aziendali, consegnare con precisione i messaggi di sistema o i promemoria di lavoro alla persona appropriata. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri Condizioni di Ricerca +|Nome Parametro|Spiegazione|Obbligatorio|Valore Predefinito| +|---|---|---|---| +|Nome Utente|Corrispondenza secondo il nome reale del personale|No|Nessuno| +|Numero Dipendente|Corrispondenza secondo il numero dipendente del personale|No|Nessuno| +|Posizione|Corrispondenza secondo la posizione o titolo del personale|No|Nessuno| +|Numero Cellulare|Corrispondenza secondo il numero di cellulare del personale|No|Nessuno| +|Nome Dipartimentale|Corrispondenza secondo il nome del dipartimento|No|Nessuno| +|Nome Chat di Gruppo|Corrispondenza secondo il nome della chat di gruppo|No|Nessuno| + +### Spiegazione Regole Condizioni +Ogni condizione di ricerca supporta i seguenti tipi di regole: +|Tipo Regola|Spiegazione|Esempio| +|---|---|---| +|Uguale|Il valore del campo è completamente uguale al valore specificato|Nome uguale a "Mario Rossi"| +|Diverso|Il valore del campo non è uguale al valore specificato|Posizione diversa da "Stagista"| +|Contiene|Il valore del campo contiene il contenuto specificato|Nome dipartimento contiene "Tecnico"| +|Non Contiene|Il valore del campo non contiene il contenuto specificato|Nome non contiene "Test"| +|Vuoto|Il valore del campo è vuoto|Numero cellulare vuoto| +|Non Vuoto|Il valore del campo non è vuoto|Numero dipendente non vuoto| + +### Impostazione Tipo Valore +|Tipo Valore|Spiegazione|Esempio| +|---|---|---| +|Valore Fisso|Inserire direttamente il valore di query specifico|"Mario Rossi", "Dipartimento Sviluppo"| +|Valore Variabile|Fare riferimento a variabili nel flusso di lavoro come valore di query|department_name| + +### Contenuto Output +|Campo Output|Spiegazione| +|---|---| +|Dati Utente (Array)|Lista utenti che soddisfano le condizioni, ogni utente contiene: ID utente univoco, nome reale, nome posizione, ecc.| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Imposta le condizioni di ricerca base**: + 1. Clicca sulla condizione di ricerca necessaria (come "Nome Utente") + 2. Seleziona la regola di corrispondenza (come "Uguale", "Contiene", ecc.) + 3. Seleziona il tipo di valore ("Valore Fisso" o "Valore Variabile") + 4. Inserisci il valore di query specifico o seleziona la variabile +2. **Aggiungi molteplici condizioni di ricerca (opzionale)**: + 1. Clicca il pulsante "Aggiungi Condizione" per aumentare ulteriori condizioni di filtro + 2. Molteplici condizioni sono predefinite come relazione "E", cioè tutte le condizioni devono essere soddisfatte +3. **Visualizza i campi di output**: + 1. Espandi la sezione "Output" per conoscere la struttura dei dati dei risultati della query + 2. Familiarizzati con il significato dei campi per fare riferimento corretto nei nodi successivi +4. **Connetti i nodi successivi**: + 1. Connetti l'output del nodo Recupero Personale ai nodi che necessitano di informazioni del personale + 2. Utilizza `NomeNodo.userData` nei nodi successivi per fare riferimento ai risultati della ricerca + +## ⚠️ Note Importanti + +### Efficienza di Ricerca +Quando la scala dell'organizzazione è grande, è necessario prestare attenzione all'impatto delle impostazioni delle condizioni di ricerca sull'efficienza: +- Dai priorità all'utilizzo di condizioni precise (come numero dipendente, numero cellulare) piuttosto che condizioni fuzzy (come nome contiene) +- Combina ragionevolmente molteplici condizioni per restringere l'ambito di ricerca +- Evita query complete non necessarie, riduci il carico del sistema + +### Permessi sui Dati +Il recupero del personale è limitato dai permessi dell'account Bot corrente: +- Può recuperare solo dipartimenti e personale che il Bot ha il permesso di accedere +- Alcune informazioni sensibili (come numero cellulare) potrebbero richiedere permessi specifici +- Assicurati che l'account Bot abbia permessi sufficienti di accesso alla struttura organizzativa + +### Tempestività dei Dati +Le informazioni del personale potrebbero cambiare, è necessario prestare attenzione: +- I risultati della ricerca riflettono lo stato della struttura organizzativa al momento attuale +- È necessaria una strategia per affrontare cambiamenti di posizione del personale, dimissioni, ecc. +- Si consiglia di aggiungere logica di verifica dei risultati nei processi critici + +## ❓ Problemi Comuni + +### Problema 1: Ho Impostato le Condizioni di Ricerca ma Non Ho Ottenuto i Risultati Previsti? +**Soluzioni**: Potrebbe essere un problema di mancata corrispondenza delle condizioni o di permessi, si consiglia: +- Verifica se i valori delle condizioni sono corretti, specialmente i riferimenti alle variabili +- Conferma che gli operatori di confronto siano utilizzati correttamente (come "Uguale" e "Contiene") +- Prova ad allentare le condizioni o utilizzare condizioni più precise (come numero dipendente) +- Verifica se l'account Bot ha i permessi per accedere alle informazioni del personale target + +### Problema 2: Come Gestire Situazioni di Omonimia? +**Soluzioni**: Il fenomeno dell'omonimia è comune nelle grandi organizzazioni: +- Combina molteplici condizioni (come nome+dipartimento) per filtrare +- Dai priorità all'utilizzo di identificatori univoci (come numero dipendente o ID utente) per la ricerca +- Aggiungi logica di giudizio dell'omonimia nell'elaborazione dei risultati (come distinzione per dipartimento) + +### Problema 3: C'è un Limite alla Quantità dei Risultati di Ricerca? +**Soluzioni**: Sì, generalmente c'è un limite al numero di restituzioni: +- Per impostazione predefinita vengono restituiti al massimo 50 record corrispondenti +- Per scenari che necessitano di interrogare grandi quantità di utenti, considera l'elaborazione in batch o l'ottimizzazione delle condizioni di ricerca +- Per scenari di ampio raggio come query di intero dipartimento, considera l'utilizzo di strumenti di report più professionali + +## 🔗 Nodi Comuni da Abbinare + +|Tipo di Nodo|Motivo dell'Abbinamento| +|---|---| +|Nodo Risposta Messaggio|Mostrare all'utente le informazioni del personale recuperate| +|Nodo Ramo Condizionale|Decidere il flusso successivo basandosi sull'esistenza di risultati di ricerca| +|Nodo Chiamata Modello Grande|Utilizzare le informazioni del personale per costruire risposte personalizzate o analisi| +|Nodo Creazione Chat di Gruppo|Creare automaticamente chat di gruppo specifiche basandosi sui risultati della ricerca| +|Nodo Richiesta HTTP|Inviare le informazioni del personale a sistemi esterni per l'elaborazione| + +--- + # 人员检索节点 ## 什么是人员检索节点？ diff --git a/docs/zh/tutorial/basic/node/Selector.md b/docs/zh/tutorial/basic/node/Selector.md index 19ddaf2d7..1cf9482b2 100644 --- a/docs/zh/tutorial/basic/node/Selector.md +++ b/docs/zh/tutorial/basic/node/Selector.md @@ -1,3 +1,139 @@ +# 🔀 Nodo Selettore + +## ❓ Cos'è il Nodo Selettore? + +Il nodo Selettore è un nodo di giudizio condizionale nei flussi di lavoro Magic Flow che permette di dividere il flusso di lavoro in percorsi di esecuzione diversi basandosi su condizioni impostate. È come un bivio stradale, dove si sceglie direzione diversa in base a situazioni diverse. Attraverso il nodo Selettore, puoi costruire flussi di lavoro intelligenti con ramificazioni logiche, implementando la funzionalità di eseguire operazioni diverse basate su condizioni diverse. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Selettore mostra l'area di impostazione delle condizioni, inclusa la configurazione di riferimento variabile, selezione condizioni (come uguale, condizione, ecc.) e valori di confronto (espressioni o valori fissi). L'interfaccia supporta la combinazione di molteplici condizioni attraverso i pulsanti "O" e "E", implementando logica di giudizio complessa. +![Nodo Selettore](https://cdn.letsmagic.cn/static/img/Selector.png) + +## 🤔 Perché Serve il Nodo Selettore? + +Nella costruzione di flussi di lavoro intelligenti, il nodo Selettore svolge il ruolo di "decisore", fornendo alla tua applicazione capacità di giudizio condizionale e selezione percorso: +- **Elaborazione Ramificazioni Logiche**: Selezionare percorsi di elaborazione diversi basandosi su condizioni diverse +- **Adattamento Multi-scenario**: Eseguire operazioni diverse per diversi input utente o stati dati +- **Implementazione Regole Aziendali**: Convertire le regole aziendali in giudizi condizionali eseguibili +- **Gestione Errori**: Selezionare flusso normale o elaborazione eccezionale basandosi sui risultati delle operazioni +- **Flussi Personalizzati**: Fornire esperienze personalizzate basandosi su caratteristiche utente o comportamenti storici + +## 🎯 Scenari Applicabili + +### 1. Guida Classificazione Utente +Guidare gli utenti verso flussi di servizio diversi basandosi sulle informazioni fornite (come età, professione, esigenze, ecc.), fornendo aiuto mirato. + +### 2. Processo di Approvazione +Decidere se necessiti di approvazione di livello superiore o approvazione diretta basandosi su importo richiesta, livello richiedente, ecc. + +### 3. Sistema Domande&Risposte Intelligente +Analizzare il tipo di domanda dell'utente, indirizzare verso flussi di risposta specialistici corrispondenti basandosi su diverse categorie di domande. + +### 4. Flusso Elaborazione Dati +Selezionare metodi di elaborazione successivi diversi basandosi su qualità dati, caratteristiche dati o risultati elaborazione. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri Base +|Nome Parametro|Spiegazione|Obbligatorio|Valore Predefinito| +|---|---|---|---| +|Riferimento Variabile|Selezionare la variabile da giudicare|Sì|Nessuno| +|Selezione Condizione|Impostare il modo di confronto, come uguale, condizione, ecc.|Sì|Uguale| +|Valore Confronto|Impostare il valore target del confronto, può essere espressione o valore fisso|Sì|Nessuno| +|Logica Combinazione Condizioni|Relazione tra molteplici condizioni, può essere "E" o "O"|No|E| + +### Spiegazione Tipi Condizione +|Tipo Condizione|Spiegazione|Tipi Dati Applicabili| +|---|---|---| +|Uguale|Giudicare se il valore della variabile è completamente identico al valore impostato|Testo, numero, valore booleano| +|Condizione|Utilizzare espressioni di condizione complesse per giudicare|Tutti i tipi| +|Valore Fisso|Confrontare con un valore fisso specifico|Testo, numero, valore booleano| +|Espressione|Utilizzare il risultato del calcolo dell'espressione per confrontare|Testo, numero, oggetto| + +### Contenuto Output +Il nodo Selettore non ha contenuto di output specifico, ma seleziona percorsi di esecuzione diversi basandosi sui risultati del giudizio condizionale: +- Quando la condizione è soddisfatta: Esegue il ramo "Corrispondente" +- Quando la condizione non è soddisfatta: Esegue il ramo "Altrimenti" + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Seleziona la variabile di giudizio**: + 1. Seleziona la variabile da giudicare dal menu a tendina + 2. Può essere input utente, output di nodi upstream o variabile globale +2. **Imposta la condizione di giudizio**: + 1. Seleziona il tipo di condizione appropriato (uguale, condizione, ecc.) + 2. Imposta il valore di confronto corrispondente secondo il tipo di condizione +3. **Configura multi-condizioni (opzionale)**: + 1. Clicca il pulsante "+" per aggiungere condizioni aggiuntive + 2. Utilizza il pulsante "E" per richiedere che tutte le condizioni siano soddisfatte contemporaneamente + 3. Utilizza il pulsante "O" per richiedere che almeno una condizione sia soddisfatta +4. **Connetti nodi downstream**: + 1. Connetti l'uscita "Corrispondente" al nodo da eseguire quando la condizione è soddisfatta + 2. Connetti l'uscita "Altrimenti" al nodo da eseguire quando la condizione non è soddisfatta + +#### Collaborazione con Altri Nodi +Il nodo Selettore generalmente necessita di essere utilizzato in combinazione con altri nodi: +1. **In Combinazione con il Nodo Salvataggio Variabili**: + 1. Utilizza il nodo Salvataggio Variabili prima del selettore per registrare le informazioni necessarie per il giudizio + 2. Dopo il giudizio del selettore, salva nuovamente lo stato del risultato +2. **In Combinazione con il Nodo Chiamata Modello Grande**: + 1. Utilizza il modello grande per generare contenuto o analisi + 2. Il selettore decide l'elaborazione successiva basandosi sui risultati dell'analisi +3. **In Combinazione con il Nodo Elaborazione Dati**: + 1. Pre-elabora e controlla i dati + 2. Il selettore seleziona il metodo di elaborazione basandosi sulle caratteristiche dei dati + +## ⚠️ Note Importanti + +### Corrispondenza Tipi Variabile +Assicurati che il tipo della variabile di giudizio corrisponda al tipo del valore di confronto, per evitare risultati inaspettati: +- Confronto numero con numero (come `5 > 3`) +- Confronto testo con testo (come `"hello" == "hello"`) +- Confronto valore booleano con valore booleano (come `true == false`) + +### Priorità Condizioni +Quando utilizzi molteplici condizioni, presta attenzione alla priorità della combinazione delle condizioni: +- La priorità di "E" è superiore a "O" +- Per condizioni complesse si consiglia di utilizzare espressioni per chiarire la priorità + +### Gestione Percorsi +Assicurati che tutti i possibili rami condizionali abbiano flussi di elaborazione corrispondenti: +- Evita percorsi "sospesi" +- Verifica se sono state gestite tutte le situazioni possibili + +## ❓ Problemi Comuni + +### Problema 1: I Risultati del Giudizio Condizionale Non Corrispondono alle Aspettative? +**Soluzioni**: Potrebbe essere che il tipo o valore della variabile non corrisponda alle aspettative: +- Verifica il valore e tipo effettivo della variabile (puoi utilizzare il nodo Codice per output informazioni variabile) +- Conferma se le condizioni di confronto sono impostate correttamente +- Per confronti di testo, presta attenzione a differenze maiuscolo/minuscolo e spazi + +### Problema 2: Come Gestire il Giudizio di Molteplici Situazioni Diverse? +**Soluzioni**: Per scenari che necessitano di giudicare molteplici situazioni diverse: +- Utilizza molteplici nodi Selettore in serie, formando una catena di giudizio completa +- Oppure utilizza prima il nodo Riconoscimento Intenzioni per classificare, poi utilizza il selettore per elaborazione ulteriore +- Situazioni complesse possono considerare l'utilizzo del nodo Esecuzione Codice per logica personalizzata + +### Problema 3: Errore nel Giudizio di Oggetti o Array del Nodo Selettore? +**Soluzioni**: Oggetti e array necessitano di elaborazione speciale: +- Utilizza espressioni per accedere a proprietà specifiche dell'oggetto (come `user.name`) +- Per array puoi utilizzare espressioni per controllare lunghezza o elementi specifici +- Per confronti di oggetti complessi si consiglia di utilizzare prima il nodo Codice per conversione a tipi semplici + +## 🔗 Nodi Comuni da Abbinare + +|Tipo di Nodo|Motivo dell'Abbinamento| +|---|---| +|Nodo Chiamata Modello Grande|Analizzare contenuto poi giudicare basandosi sui risultati| +|Nodo Salvataggio Variabili|Registrare risultati di giudizio per riferimento nei flussi successivi| +|Nodo Esecuzione Codice|Gestire logica di giudizio complessa o conversione dati| +|Nodo Risposta Messaggio|Rispondere contenuti diversi basandosi su condizioni diverse| +|Nodo Richiesta HTTP|Selezionare modi di elaborazione diversi basandosi sui risultati della richiesta| + +--- + # 选择器节点 ## 什么是选择器节点？ 选择器节点是Magic Flow工作流中的条件判断节点，它允许您根据设定的条件将工作流分为不同的执行路径。就像在道路上的分叉口，根据不同情况选择不同的前进方向。通过选择器节点，您可以构建具有逻辑分支的智能工作流，实现根据不同条件执行不同操作的功能。 diff --git a/docs/zh/tutorial/basic/node/Spreadsheet-parsing.md b/docs/zh/tutorial/basic/node/Spreadsheet-parsing.md index 0815d454b..a357ac336 100644 --- a/docs/zh/tutorial/basic/node/Spreadsheet-parsing.md +++ b/docs/zh/tutorial/basic/node/Spreadsheet-parsing.md @@ -1,3 +1,131 @@ +# 📊 Nodo Parsing Fogli di Calcolo + +## 🔍 Introduzione al Nodo + +Il nodo Parsing Fogli di Calcolo è uno strumento specializzato per estrarre e analizzare il contenuto dei file Excel. A differenza del normale nodo di parsing documenti, il nodo Parsing Fogli di Calcolo è in grado di riconoscere la struttura del foglio di calcolo, preservando informazioni chiave come fogli di lavoro, righe, colonne, ecc., rendendo i dati utilizzabili in modo più **strutturato (diversamente dal parsing documenti)** nel flusso di lavoro. Senza bisogno di conoscenze di programmazione, con una semplice configurazione, puoi facilmente ottenere tutti i dati nel foglio Excel e salvarli e trasmetterli secondo la **struttura** originale del foglio. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Parsing Fogli di Calcolo include due parti principali: input e output. La parte input può impostare la fonte del file (lista file, singolo file, ecc.), la parte output è invece la struttura dati del foglio di calcolo parsato, contenente informazioni file e contenuto del foglio. +![Nodo Parsing Fogli di Calcolo](https://cdn.letsmagic.cn/static/img/Spreadsheet-parsing.png) + +## 🤔 Perché Serve il Nodo Parsing Fogli di Calcolo + +Nel lavoro quotidiano, i file Excel sono un formato comune per memorizzare e trasmettere dati. Attraverso il nodo Parsing Fogli di Calcolo, puoi: +- **Acquisizione Automatica Contenuto**: Leggere automaticamente i dati nei file Excel, eliminando il processo noioso di copia-incolla manuale +- **Elaborazione Batch**: Elaborare in batch molteplici file di fogli di calcolo, migliorando l'efficienza lavorativa +- **Analisi Strutturata**: Convertire i dati del foglio in formato strutturato, facilitando l'analisi intelligente e l'elaborazione dei nodi successivi +- **Elaborazione Intelligente**: Utilizzare modelli grandi per comprendere e operare sui dati del foglio, implementando l'elaborazione intelligente dei dati + +## 🎯 Scenari Applicabili + +Il nodo Parsing Fogli di Calcolo è applicabile ai seguenti scenari: + +### **Scenario 1: Automazione Analisi Dati**: +Leggere automaticamente file Excel come fogli presenze dipendenti, report vendite, ecc., effettuare analisi dati e generare report riassuntivi + +### **Scenario 2: Elaborazione Import Dati**: +Importare cataloghi prodotti, dati clienti, ecc. in fogli di calcolo, e salvare i dati nel sistema o nella knowledge base + +### **Scenario 3: Elaborazione Intelligente Moduli**: +Analizzare moduli Excel caricati dagli utenti, effettuare validazione dati, pulizia e conversione + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri di Input +|Nome Parametro|Spiegazione|Obbligatorio|Valore Predefinito| +|---|---|---|---| +|Lista File|Scegli la lista di file Excel da parsare, può essere la collezione di file passata dal nodo precedente|Obbligatorio|Nessuno| +|File|Singolo oggetto file foglio di calcolo, alternativo alla lista file|Condizionalmente Obbligatorio|Nessuno| +|Nome File|Nome del file del foglio di calcolo, generalmente utilizzato insieme al link file|Condizionalmente Obbligatorio|Nessuno| +|Link File|Link di download o percorso di accesso del foglio di calcolo|Condizionalmente Obbligatorio|Nessuno| + +### Parametri di Output +Il nodo Parsing Fogli di Calcolo restituisce un oggetto file foglio strutturato, contenente le seguenti informazioni: +|Contenuto Output|Spiegazione| +|---|---| +|File Foglio (files_spreadsheet)|File del foglio di calcolo| +|Nome File (file_name)|Nome del file| +|Indirizzo File (file_url)|Indirizzo di accesso del foglio di calcolo| +|Estensione File (file_extension)|Estensione formato file, come xlsx, xls, ecc.| +|Foglio di Lavoro (sheet)|Contiene i dati dei fogli di lavoro nel foglio di calcolo| +|Nome Foglio (sheet_name)|Nome del foglio di lavoro| +|Righe (rows)|Collezione di dati delle righe nel foglio di lavoro| +|Indice Riga (row_index)|Numero di sequenza della riga, inizia da 0| +|Celle (cells)|Collezione di dati delle celle nella riga| +|Valore (value)|Valore effettivo della cella| +|Indice Colonna (column_index)|Numero di sequenza della colonna dove si trova la cella| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Aggiungi Nodo**: Trascina il nodo "Parsing Fogli di Calcolo" dal pannello nodi al canvas del flusso di lavoro +2. **Connetti Nodo Precedente**: Connetti l'output del nodo precedente (come "Nodo Inizio" o "Nodo Caricamento File", ecc.) al nodo Parsing Fogli di Calcolo +3. **Imposta Parametri di Input**: + 1. Se il nodo precedente fornisce una lista file, seleziona il parametro "Lista File" e fai riferimento alla variabile corrispondente + 2. Se necessiti di parsare un file specifico, compila i parametri "Nome File" e "Link File" +4. **Salva Configurazione**: Clicca il pulsante salva per confermare le impostazioni del nodo +5. **Connetti Nodi Successivi**: Connetti l'output del nodo Parsing Fogli di Calcolo ai nodi downstream (come "Chiamata Modello Grande" o "Esecuzione Codice", ecc.) + +### Tecniche Avanzate +1. **Elaborazione Batch di Molteplici Fogli**: + 1. Configura il nodo Ciclo per scorrere ogni foglio di calcolo nella lista file + 2. Utilizza il nodo Parsing Fogli di Calcolo all'interno del ciclo per elaborare singoli file + 3. Utilizza il nodo Salvataggio Variabili per memorizzare i risultati dell'elaborazione +2. **Conversione Dati Foglio**: + 1. In combinazione con il nodo Esecuzione Codice, puoi effettuare conversioni di formato sui dati del foglio parsato + 2. Ad esempio convertire i dati del foglio in formato JSON o CSV +3. **Comprensione Intelligente Foglio**: + 1. Passa i dati del foglio parsato al nodo Chiamata Modello Grande + 2. Utilizza prompt per guidare il modello grande a comprendere la struttura del foglio e il significato dei dati + 3. Fai generare al modello grande riassunti dei dati del foglio o rispondere a domande correlate + +## ⚠️ Note Importanti + +### Supporto Formati File +- Formati file supportati includono: `.xlsx`, `.xls`, `.csv` +- Per file di fogli in altri formati, potrebbe essere necessario convertirli prima nei formati sopra menzionati per il parsing +- Fogli Excel particolarmente complessi (come quelli contenenti macro, grafici, ecc.) potrebbero influenzare l'effetto del parsing + +### Limitazioni Quantità Dati +- Per fogli di grandi dimensioni (come dati con decine di migliaia di righe), il processo di parsing potrebbe richiedere più tempo +- Si consiglia di effettuare elaborazione a frammenti per fogli grandi, o filtrare prima la parte di dati necessaria per il parsing +- In caso di problemi di performance, puoi considerare l'utilizzo del nodo Esecuzione Codice per ottimizzazioni + +### Codifica e Lingua +- Per fogli contenenti caratteri speciali o contenuti multilingue, assicurati che il file utilizzi codifica UTF-8 +- Caratteri cinesi e altri non inglesi potrebbero necessitare di elaborazione aggiuntiva dopo il parsing per essere visualizzati correttamente + +## ❓ Problemi Comuni + +### Risultato Parsing Vuoto +**Problema**: Ho configurato il nodo Parsing Fogli di Calcolo, ma l'output è vuoto o senza dati. + +**Soluzioni**: +1. Verifica se il file di input è valido, se il link file è accessibile +2. Conferma che il file Excel contenga effettivamente dati, non un foglio vuoto +3. Verifica se il formato file è supportato, formati Excel troppo vecchi potrebbero necessitare conversione +4. Prova prima a scaricare il file localmente, poi caricarlo sulla piattaforma per l'elaborazione + +### Dati Parsing Incompleti +**Problema**: Vengono parsati solo alcuni dati del foglio, alcuni contenuti sono persi o errati. + +**Soluzioni**: +1. Verifica se il foglio originale contiene celle unite, questo potrebbe influenzare l'effetto del parsing +2. Conferma se il foglio contiene formati speciali (come formule, grafici, ecc.), questi potrebbero non essere completamente parsabili +3. Per file Excel con molteplici fogli di lavoro, assicurati di prestare attenzione al foglio corretto +4. Prova a convertire Excel in formato semplice (come CSV) prima del parsing + +### Impossibile Riconoscere Formato Data +**Problema**: Le date nel foglio dopo il parsing diventano numeri o altri formati. + +**Soluzioni**: +1. In Excel imposta esplicitamente il formato della colonna data come formato data +2. Dopo il parsing utilizza il nodo Esecuzione Codice per convertire il formato data +3. Utilizza il nodo Chiamata Modello Grande per riconoscere e convertire il formato data + +--- + # 电子表格解析节点 ## 节点介绍 电子表格解析节点是一个专门用于提取和解析Excel表格文件内容的工具。与普通的文档解析节点不同，电子表格解析节点能够识别表格的结构，保留工作表、行、列等关键信息，使得数据在工作流中可以更加**结构化（区别于文档解析）**地使用。无需编程知识，只要简单配置，即可轻松获取Excel表格中的所有数据，并按照表格原有的**结构**进行保存和传递。 diff --git a/docs/zh/tutorial/basic/node/Subprocess.md b/docs/zh/tutorial/basic/node/Subprocess.md index 482405101..0ccb08f39 100644 --- a/docs/zh/tutorial/basic/node/Subprocess.md +++ b/docs/zh/tutorial/basic/node/Subprocess.md @@ -1,3 +1,124 @@ +# 🔄 Nodo Sottoprocesso + +## ❓ Che Cos'è il Nodo Sottoprocesso? + +Il nodo Sottoprocesso è uno strumento organizzativo potente che permette di isolare una parte di moduli funzionali, formando un flusso separato, e poi richiamarlo nel flusso principale. Proprio come quando si scrive un articolo, dividiamo il contenuto in capitoli e paragrafi, il sottoprocesso aiuta a suddividere flussi di lavoro complessi in parti più piccole e gestibili. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Sottoprocesso è composta da aree di selezione flusso e configurazione flusso. L'area di configurazione contiene principalmente due parti: impostazioni parametri di input e ricezione parametri di output, dove puoi configurare i dati da scambiare con il sottoprocesso. +![Nodo Sottoprocesso](https://cdn.letsmagic.cn/static/img/Subprocess.png) + +## 🤔 Perché Serve il Nodo Sottoprocesso? + +Nella progettazione di flussi di lavoro complessi, se si mettono tutte le funzionalità in un singolo flusso, il diagramma del flusso diventa enorme e difficile da gestire. Il nodo Sottoprocesso può aiutarti a: +1. **Semplificare il Flusso Principale**: Separare la logica complessa nei sottoprocessi, rendendo il flusso principale più chiaro +2. **Migliorare la Riutilizzabilità**: Un sottoprocesso può essere richiamato da molteplici flussi principali diversi +3. **Facilitare la Collaborazione di Team**: Diversi membri del team possono concentrarsi sullo sviluppo di sottoprocessi diversi +4. **Aumentare l'Efficienza di Manutenzione**: Quando si modifica una funzionalità, è necessario aggiornare solo il sottoprocesso corrispondente + +## 🎯 Scenari Applicabili + +### Scenario 1: Elaborazione Modularizzata di Compiti Complessi +Quando il tuo assistente AI deve eseguire una serie di operazioni complesse (come elaborazione dati multi-step, giudizi condizionali multipli, ecc.), puoi suddividere queste operazioni in molteplici sottoprocessi, rendendo la struttura complessiva più chiara. + +### Scenario 2: Incapsulamento di Funzionalità Riutilizzabili +Per funzionalità che necessitano di essere riutilizzate in molteplici luoghi (come autenticazione utente, conversione formato dati, ecc.), puoi incapsularle come sottoprocessi, realizzando sviluppo una volta, utilizzo multiplo. + +### Scenario 3: Collaborazione di Team in Progetti di Grandi Dimensioni +In progetti di grandi dimensioni, puoi assegnare moduli funzionali diversi a diversi membri del team per sviluppare sottoprocessi, poi integrarli nel flusso principale, migliorando l'efficienza della collaborazione di team. + +## ⚙️ Spiegazione Parametri del Nodo + +Il nodo Sottoprocesso contiene principalmente configurazione parametri di input e output: + +### Parametri di Input +|Nome Parametro|Descrizione Parametro|Obbligatorio|Tipo Parametro|Valore Predefinito| +|---|---|---|---|---| +|Nome Sottoprocesso|Nome del sottoprocesso da richiamare|Sì|Selezione Dropdown|Nessuno| +|Parametri di Input|Dopo aver selezionato il sottoprocesso, dati passati al sottoprocesso|Sì|Stringa/Numero/Valore Booleano ecc.|Nessuno| + +Il nodo Sottoprocesso permette di impostare molteplici parametri di input, ogni parametro ha il proprio nome, tipo e valore. Questi parametri verranno passati come dati iniziali per l'utilizzo del sottoprocesso. + +### Parametri di Output +|Nome Parametro|Descrizione Parametro|Tipo Parametro| +|---|---|---| +|Output (output)|Riceve il risultato restituito dal sottoprocesso|Stringa/Numero/Valore Booleano ecc.| + +I parametri di output servono a ricevere i valori restituiti dopo il completamento dell'esecuzione del sottoprocesso, puoi utilizzare questi valori nei nodi successivi. + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Crea Sottoprocesso**: + 1. Crea un nuovo flusso sulla piattaforma Magic + 2. Configura nodi di inizio e fine appropriati + 3. Progetta la logica interna del sottoprocesso +2. **Aggiungi Nodo Sottoprocesso nel Flusso Principale**: + 1. Trascina il nodo Sottoprocesso nel canvas del flusso principale + 2. Connetti nodi precedenti e successivi +3. **Configura Nodo Sottoprocesso**: + 1. Nel menu dropdown ID Sottoprocesso seleziona il sottoprocesso da richiamare + 2. Imposta parametri di input: clicca il pulsante "+" per aggiungere parametri, specifica nome parametro, tipo e valore + 3. Imposta parametri di output: specifica il nome della variabile per ricevere il risultato restituito dal sottoprocesso +4. **Salva e Testa**: + 1. Salva la progettazione del flusso principale + 2. Esegui il flusso principale e verifica se il sottoprocesso viene eseguito come previsto + +### Tecniche Avanzate +1. **Ottimizzazione Passaggio Parametri**: + 1. Utilizza il modo riferimento variabile per passare parametri, può passare dinamicamente l'output del nodo precedente + 2. Per strutture dati complesse, puoi utilizzare formato JSON per il passaggio, migliorando la capacità di scambio dati +2. **Gestione Errori**: + 1. Aggiungi nodi di giudizio condizionale nel sottoprocesso, gestisci situazioni eccezionali che potrebbero verificarsi + 2. Restituisci lo stato di esecuzione attraverso parametri di output, fai sapere al flusso principale se il sottoprocesso è stato eseguito con successo +3. **Sottoprocessi Annidati**: + 1. Nel sottoprocesso puoi richiamare nuovamente altri sottoprocessi, formando strutture annidate multilivello + 2. Presta attenzione a controllare la profondità di annidamento, evita complessità eccessiva che renda difficile la manutenzione + +## ⚠️ Note Importanti + +### Evita Chiamate Circolari +Non richiamare il flusso padre nel sottoprocesso, questo causerà chiamate circolari infinite, consumando infine le risorse di sistema. + +### Corrispondenza Tipi Parametri +Assicurati che i tipi dei parametri passati al sottoprocesso corrispondano ai tipi attesi dal sottoprocesso, tipi non corrispondenti potrebbero causare errori di esecuzione del sottoprocesso. + +### Gestione Versioni Flusso +Quando modifichi il sottoprocesso, presta attenzione al fatto che potrebbe influenzare tutti i flussi principali che richiamano quel sottoprocesso. Si consiglia di creare prima una copia del sottoprocesso per testare prima di modifiche importanti. + +### Limitazioni Risorse +Anche i sottoprocessi consumano risorse di sistema, sottoprocessi eccessivamente annidati potrebbero causare calo delle prestazioni. Si consiglia di controllare che il livello di annidamento non superi i 3 livelli. + +## ❓ Problemi Comuni + +### Impossibile Ottenere l'Output del Sottoprocesso nel Flusso Principale +**Problema**: Ho configurato il nodo Sottoprocesso, ma non riesco a ottenere il risultato di output del sottoprocesso nel flusso principale. + +**Soluzioni**: +- Verifica se il sottoprocesso ha impostato correttamente i parametri di output del nodo finale +- Conferma che la configurazione del nome variabile di output nel nodo Sottoprocesso sia corretta +- Verifica se il sottoprocesso viene eseguito normalmente fino al completamento, senza rimanere bloccato in qualche fase + +### Esecuzione Sottoprocesso Fallita ma Senza Messaggio di Errore +**Problema**: Il sottoprocesso non viene eseguito come previsto, ma il sistema non mostra informazioni di errore chiare. + +**Soluzioni**: +- Testa il sottoprocesso separatamente, verifica se può funzionare normalmente +- Verifica se i parametri di input vengono passati correttamente +- Aggiungi nodi di log o nodi di risposta messaggio nel sottoprocesso, output informazioni di processo intermedio, aiutando a localizzare il problema + +## 🔗 Nodi Comuni da Abbinare + +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Ramificazione Condizionale|Decide il percorso successivo del flusso in base al risultato di esecuzione del sottoprocesso| +|Nodo Salvataggio Variabili|Salva il risultato di output del sottoprocesso come variabile, per utilizzo successivo| +|Nodo Chiamata Modello Grande|Elabora i dati restituiti dal sottoprocesso, genera risposte più intelligenti| +|Nodo Risposta Messaggio|Mostra all'utente il risultato elaborato dal sottoprocesso| + +--- + # 子流程节点 ## 什么是子流程节点？ 子流程节点是一个强大的组织工具，它允许您将一部分功能模块独立出来，形成单独的流程，然后在主流程中调用这个子流程。就像在写文章时，我们会将内容分为章节和段落，子流程就是帮助您将复杂工作流拆分成更小、更易管理的部分。 diff --git a/docs/zh/tutorial/basic/node/Text-segmentation.md b/docs/zh/tutorial/basic/node/Text-segmentation.md index 5a979e901..99eaecb04 100644 --- a/docs/zh/tutorial/basic/node/Text-segmentation.md +++ b/docs/zh/tutorial/basic/node/Text-segmentation.md @@ -1,3 +1,99 @@ +# ✂️ Nodo ## 🤔 Perché Serve il Nodo Segmentazione Testo? + +Nell'elaborazione di grandi quantità di testo, il blocco di testo intero spesso è troppo grande, non conveniente per analisi precise e elaborazione. Il nodo Segmentazione Testo risolve questo problema: +1. **Limitazioni Elaborazione Modello Grande**: I modelli di linguaggio di grandi dimensioni solitamente hanno limiti sulla quantità di caratteri in input, dopo la segmentazione possono essere elaborati in batch +2. **Elaborazione Raffinata**: Dividere testi lunghi in piccoli frammenti, conveniente per elaborazioni raffinate su contenuti specifici +3. **Migliorare l'Efficienza di Elaborazione**: Effettuare segmentazioni ragionevoli del testo, può migliorare l'efficienza di analisi ed elaborazione successive +4. **Facilitare Archiviazione e Ricerca**: I frammenti di testo dopo la segmentazione sono più adatti all'archiviazione in sistemi come database vettoriali, migliorando la precisione di ricercatazione Testo +## ❓ Che Cos'è il Nodo Segmentazione Testo? + +Il nodo Segmentazione Testo è un nodo di elaborazione dati speciale nel flusso di lavoro Magic, utilizzato principalmente per dividere testi lunghi secondo strategie specifiche in frammenti di testo più piccoli. Questo nodo è particolarmente utile nell'elaborazione di grandi quantità di dati testuali, potendo dividere contenuti testuali troppo lunghi in blocchi adatti all'elaborazione dei modelli grandi, migliorando efficienza e accuratezza dell'elaborazione. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Segmentazione Testo è composta principalmente da aree di input e output. Nell'area di input, puoi specificare il contenuto testuale da segmentare o fare riferimento a variabili; nell'area di output, puoi scegliere il formato di output e impostare il nome della variabile risultato. +![Nodo Segmentazione Testo](https://cdn.letsmagic.cn/static/img/Text-segmentation.png) + +## 为什么需要文本切割节点？ +在处理大量文本时，整块文本往往过于庞大，不便于精确分析和处理。文本切割节点解决了这个问题： +1. **大模型处理限制**：大语言模型通常有输入字符数量限制，切割后可分批处理 +2. **精细化处理**：将长文本切割成小片段，便于针对特定内容进行精细处理 +3. **提高处理效率**：对文本进行合理切分，可以提高后续分析和处理的效率 +4. **便于存储和检索**：切割后的文本片段更适合存入向量数据库等系统，提高检索精度 +## 🎯 Scenari Applicabili + +### Scenario 1: Costruzione Knowledge Base Documenti Lunghi +Quando necessiti di importare documenti lunghi (come manuali prodotto, report di ricerca) nella knowledge base, puoi prima utilizzare il nodo Segmentazione Testo per dividere il documento in frammenti di dimensione appropriata, poi importarli nel database vettoriale, questo può migliorare la precisione di ricerca successiva. + +### Scenario 2: Elaborazione Testi di Grande Scala +Nell'elaborazione di report giornalistici, feedback clienti e altri testi di grande scala, puoi prima segmentare in paragrafi o frasi, poi analizzare uno per uno, estraendo informazioni chiave o tendenze sentimentali. + +### Scenario 3: Elaborazione Messaggi Storici Conversazione +Nell'elaborazione di registrazioni storiche di conversazioni lunghe, puoi utilizzare il nodo Segmentazione Testo per segmentare i messaggi storici secondo tempo o tema, conveniente per analizzare il filo della conversazione o estrarre informazioni chiave. +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri di Input +|Nome Parametro|Descrizione|Obbligatorio|Tipo Parametro|Valore Esempio| +|---|---|---|---|---| +|Testo Lungo|Contenuto testuale da segmentare, può essere input diretto o riferimento variabile|Sì|Testo/Riferimento Variabile|"Questo è un contenuto testuale molto lungo..." oppure | + +### Parametri di Output +|Nome Parametro|Descrizione|Tipo Parametro|Valore Esempio| +|---|---|---|---| +|Tipo Output|Formato di output del testo dopo segmentazione, può scegliere "Frammenti Testo" o "Array Stringhe"|Selezione|Frammenti Testo| +|Nome Variabile Output|Imposta il nome della variabile del risultato di output, per utilizzo nei nodi successivi|Testo|split_texts| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Aggiungi Nodo Segmentazione Testo**: Nell'editor del flusso di lavoro, trascina il nodo Segmentazione Testo nel canvas +2. **Configura Testo di Input**: + 1. Input diretto del contenuto testuale nel box di input, oppure + 2. Clicca il pulsante "@" per selezionare dalla lista dropdown la variabile contenente testo (come output del nodo precedente) +3. **Imposta Formato di Output**: + 1. Scegli "Frammenti Testo": formato di output è il formato standard utilizzato internamente dal sistema, adatto per operazioni successive come ricerca vettoriale + 2. Scegli "Array Stringhe": output è array di testo ordinario, adatto per elaborazioni e visualizzazioni generali +4. **Imposta Nome Variabile Output**: Input un nome di variabile significativo, come "split_texts", conveniente per riferimento nei nodi successivi +5. **Connetti Nodi Successivi**: Connetti il nodo Segmentazione Testo con nodi di elaborazione successivi, formando un flusso di lavoro completo + +### Tecniche Avanzate +1. **Input Combinazione Variabili**: Puoi combinare molteplici variabili in un testo lungo per poi segmentarlo, ad esempio: `@input_utente + "\n\n" + @storico` +2. **Combinazione con Giudizio Condizionale**: Puoi impostare nodi condizionali, effettuando segmentazione solo quando la lunghezza del testo supera un certo valore +3. **Elaborazione Batch**: In combinazione con nodi ciclo, puoi elaborare in batch molteplici input testuali +## ⚠️ Note Importanti + +### Limitazioni Lunghezza Testo +Quando il testo di input è troppo lungo, potrebbe influenzare le prestazioni del sistema. Si consiglia di effettuare pre-elaborazione o importazione a frammenti per testi particolarmente lunghi (come documenti superiori a 10MB). + +### Impatto Qualità Segmentazione +La qualità della segmentazione testo influenza direttamente l'effetto di elaborazione successiva. Il sistema attualmente adotta strategia di segmentazione fissa, in futuro verranno aperti più scelte di strategia di segmentazione. + +### Norme Denominazione Variabili +Imposta nomi significativi per le variabili di output, evita l'utilizzo di nomi generici come "result", per evitare confusione nell'output di nodi diversi in flussi di lavoro complessi. +## ❓ Problemi Comuni + +### Problema 1: Dopo la Segmentazione Testo i Frammenti Sono Troppi, Come Gestirli? +**Soluzioni**: +1. Considera di filtrare i frammenti dopo segmentazione, mantenendo solo contenuti importanti +2. In combinazione con nodi ciclo elabora questi frammenti in batch +3. Nei nodi successivi imposta limiti di elaborazione, come elaborare solo i primi N frammenti + +### Problema 2: Dopo la Segmentazione i Frammenti di Testo Perdono Correlazione Contestuale, Come Mantenere Coerenza Semantica? +**Soluzioni**: +1. Assicurati che la granularità di segmentazione sia appropriata, non segmentare troppo finemente +2. Nell'elaborazione successiva, puoi considerare di introdurre contenuti di frammenti adiacenti come contesto +3. Nell'utilizzo di modelli grandi per l'elaborazione, puoi specificare chiaramente nella parola chiave che questi frammenti di testo sono correlati +## 🔗 Nodi Comuni da Abbinare + +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Parsing Documenti|Prima analizza documenti, poi effettua segmentazione testo| +|Nodo Archiviazione Vettoriale|Archivia i frammenti di testo dopo segmentazione nel database vettoriale| +|Nodo Chiamata Modello Grande|Analizza ed elabora i frammenti di testo dopo segmentazione| +|Nodo Ciclo|Elabora in batch i molteplici frammenti di testo dopo segmentazione| + +--- + # 文本切割节点 ## 什么是文本切割节点？ 文本分割节点是Magic工作流中的一个特殊数据处理节点，主要用于将长文本按照特定策略分割成更小的文本片段。这个节点在处理大量文本数据时特别有用，能够将过长的文本内容切分成适合大模型处理的小块，提高处理效率和准确性。 @@ -10,7 +106,7 @@ ## 为什么需要文本切割节点？ 在处理大量文本时，整块文本往往过于庞大，不便于精确分析和处理。文本切割节点解决了这个问题： 1. **大模型处理限制**：大语言模型通常有输入字符数量限制，切割后可分批处理 -2. **精细化处理**：将长文本切割成小片段，便于针对特定内容进行精细处理 +2. **精细化处理**：将长文本切割成小段，便于针对特定内容进行精细处理 3. **提高处理效率**：对文本进行合理切分，可以提高后续分析和处理的效率 4. **便于存储和检索**：切割后的文本片段更适合存入向量数据库等系统，提高检索精度 ## 适用场景 diff --git a/docs/zh/tutorial/basic/node/Tool.md b/docs/zh/tutorial/basic/node/Tool.md index 3924ff335..71a4cb9aa 100644 --- a/docs/zh/tutorial/basic/node/Tool.md +++ b/docs/zh/tutorial/basic/node/Tool.md @@ -1,3 +1,143 @@ +# 🔧 Nodo Strumento + +## ❓ Che Cos'è il Nodo Strumento? + +Il nodo Strumento è un nodo potente in Magic Flow che permette di richiamare e utilizzare vari strumenti preimpostati nel flusso di lavoro. Come un coltellino svizzero multifunzione, il nodo Strumento aiuta a eseguire compiti specifici, come elaborazione dati, ricerca informazioni o operazioni automatizzate. Puoi utilizzare questi strumenti in due modi: attraverso descrizione in linguaggio naturale (chiamata modello grande) o impostazione diretta parametri (chiamata parametri), soddisfacendo diverse esigenze di scenario. + +**Spiegazione Interfaccia:** + +L'interfaccia del nodo Strumento è composta principalmente da area di selezione modalità chiamata e area configurazione parametri. Nella parte superiore puoi scegliere modalità "Chiamata Modello Grande" o "Chiamata Parametri", sotto c'è l'area configurazione parametri di input personalizzata dal sistema, supporta aggiunta di molteplici parametri e relative espressioni. +![Nodo Strumento](https://cdn.letsmagic.cn/static/img/Tool.png) + +## 🤔 Perché Serve il Nodo Strumento? + +Nella costruzione di flussi di lavoro intelligenti, spesso necessiti di eseguire compiti standardizzati o richiamare funzionalità specifiche. Il nodo Strumento esiste proprio per risolvere questo problema: +1. **Estensione Funzionale**: Estende le capacità di Magic Flow, facendo sì che il flusso di lavoro possa eseguire compiti più professionali +2. **Operazioni Standardizzate**: Fornisce interfaccia unificata per richiamare vari strumenti, semplificando la progettazione del flusso di lavoro +3. **Chiamata Flessibile**: Supporta molteplici modalità di chiamata, facile da utilizzare anche senza background tecnico +4. **Automazione Flusso**: Trasforma operazioni manuali in flussi automatizzati, migliorando efficienza e consistenza + +## 🎯 Scenari Applicabili + +Il nodo Strumento è applicabile a vari scenari, inclusi ma non limitati a: +1. **Ricerca Informazioni**: Richiama strumenti di ricerca per ottenere informazioni in tempo reale o conoscenze professionali +2. **Elaborazione Dati**: Utilizza strumenti di conversione dati per elaborare e formattare dati del flusso di lavoro +3. **Operazioni Automatizzate**: Attiva compiti automatizzati, come invio notifiche o creazione calendario +4. **Miglioramento Assistente Intelligente**: Aggiunge capacità di strumenti pratici ai chatbot, come ricerca meteo o traduzione testo + +## ⚙️ Spiegazione Parametri del Nodo + +### Spiegazione Parametri di Input +I parametri di input del nodo Strumento si dividono principalmente in due categorie: impostazioni modalità chiamata e configurazione parametri strumento. +|Nome Parametro|Descrizione|Obbligatorio|Valore Predefinito| +|---|---|---|---| +|Modalità Chiamata|Scegli modalità chiamata strumento, include [Chiamata Modello Grande] e [Chiamata Parametri]|Sì|Chiamata Modello Grande| +|Selezione Strumento|Scegli nome strumento da utilizzare|Sì|Nessuno| +|Modello|Utilizzando [Chiamata Modello Grande], seleziona modello da utilizzare|Sì|GPT-4o| +|Parola Chiave|Utilizza parola chiave per guidare modello grande, assicurando utilizzo accurato, supporta utilizzo @ per riferimento variabili|No|Nessuno| + +### Spiegazione Output +Dopo l'esecuzione del nodo Strumento, verranno restituiti i seguenti contenuti: +|Nome Output|Descrizione|Esempio| +|---|---|---| +|Testo Output|Testo risultato esecuzione strumento|"Meteo attuale Pechino: Sereno, 25°C"| +|Stato Esecuzione|Stato esecuzione strumento, successo o fallimento|"success"| +|Informazioni Errore|In caso di fallimento esecuzione, contiene dettagli errore|"Timeout chiamata API"| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Aggiungi Nodo Strumento** + 1. Trascina il nodo "Strumento" dal pannello nodi al canvas del flusso di lavoro + 2. Connetti il nodo con altri nodi nel flusso di lavoro +2. **Seleziona Modalità Chiamata** + 1. Nel pannello configurazione nodo seleziona "Chiamata Modello Grande" o "Chiamata Parametri" + 2. Chiamata Modello Grande: Adatta per utilizzare strumento attraverso descrizione in linguaggio naturale + 3. Chiamata Parametri: Adatta per utilizzare strumento attraverso configurazione diretta parametri +3. **Configura Parametri** + 1. Clicca pulsante "Aggiungi" per aggiungere parametri necessari allo strumento + 2. Compila nome parametro, imposta se obbligatorio + 3. Seleziona tipo espressione appropriato (come testo, numero, ecc.) + 4. Compila valore parametro o espressione +4. **Imposta Parametri Annidati (se necessario)** + 1. Per strumenti complessi, clicca pulsante "+" accanto al parametro per aggiungere sottoparametri + 2. Configura sottoparametri nello stesso modo +5. **Configura Output** + 1. Nella sezione "Output" seleziona formato output (predefinito testo) + 2. Abilita o disabilita voci output specifiche secondo necessità + +### Tecniche Avanzate +1. **Utilizzo Riferimento Variabili** + 1. Seleziona opzione "Utilizza @variabili flusso" per utilizzare simbolo @ per riferimento variabili nel flusso di lavoro + 2. Ad esempio: Nell valore parametro input "@domanda_utente" utilizza valore variabile "domanda_utente" nel flusso di lavoro +2. **Calcolo Dinamico Parametri** + 1. Puoi utilizzare formule di calcolo semplici nelle espressioni + 2. Ad esempio: "{{count + 1}}" calcolerà automaticamente risultato di valore variabile count + 1 +3. **Utilizzo Risultati Strumento in Giudizi Condizionali** + 1. L'output del nodo Strumento può essere utilizzato come input del nodo ramificazione condizionale + 2. Puoi scegliere diversi rami di elaborazione in base al risultato di esecuzione dello strumento + +## ⚠️ Note Importanti + +### Attenzione Configurazione Parametri +1. **Norme Denominazione Parametri** + 1. I nomi parametri dovrebbero essere concisi e chiari, riflettere lo scopo del parametro + 2. Evita spazi e caratteri speciali, si consiglia utilizzo lettere inglesi, numeri e trattini bassi + 3. Utilizza nomi descrittivi, come "search_query" invece di semplice "q" + +2. **Tipo Valori Parametri** + 1. Assicurati che il tipo di valore parametro sia consistente con quanto atteso dallo strumento (come numero, valore booleano, testo, ecc.) + 2. Per tipi array o oggetto, presta attenzione alla correttezza formato JSON + 3. Per tipi data e ora presta attenzione ai requisiti di formato (come ISO8601) + +3. **Gestione Parametri Obbligatori** + 1. Assicurati che tutti i parametri obbligatori abbiano valori appropriati + 2. Nell'utilizzo di riferimenti variabili, assicurati che le variabili abbiano certamente valori al momento dell'esecuzione + 3. Considera di aggiungere valori predefiniti o opzioni di fallback per parametri critici + +### Gestione Errori +1. **Tipi Errori Comuni** + 1. Errori Parametri: Formato parametro non corretto o parametri obbligatori mancanti + 2. Limitazioni Chiamata: Frequenza chiamata API supera limiti + 3. Errori Connessione: Problemi di rete causano fallimento chiamata + +2. **Soluzioni** + 1. Utilizza nodi ramificazione condizionale per verificare stato esecuzione strumento + 2. Progetta schemi di fallback per operazioni critiche + 3. Aggiungi logica di retry per gestire errori temporanei + +## ❓ Problemi Comuni + +### Problema 1: Come Scegliere la Modalità di Chiamata Appropriata? +**Soluzioni**: La scelta dipende dalle tue esigenze e background: +- Chiamata Modello Grande: Adatta per utenti non familiari con dettagli tecnici, può descrivere compiti attraverso linguaggio naturale +- Chiamata Parametri: Adatta per scenari che necessitano controllo preciso, impostazione parametri più diretta e controllabile + +### Problema 2: Cosa Fare se il Risultato di Esecuzione Strumento Non Corrisponde alle Attese? +**Soluzioni**: Verifica i seguenti punti: +- I valori dei parametri sono compilati correttamente, specialmente formato e tipo dati +- Nella chiamata modello grande, la parola chiave è sufficientemente chiara e specifica +- Lo strumento stesso ha limitazioni funzionali o requisiti speciali +- Nell'utilizzo di riferimenti variabili, i valori delle variabili corrispondono alle attese + +### Problema 3: Come Gestire Strumenti che Necessitano Autenticazione? +**Soluzioni**: Secondo i requisiti di autenticazione dello strumento: +- Utilizza campi parametri di autenticazione dedicati (come api_key, token, ecc.) +- Per autenticazione OAuth, potrebbe essere necessario ottenere prima token di accesso poi utilizzare +- Presta attenzione a proteggere informazioni di autenticazione sensibili, evita codifica diretta nel flusso di lavoro + +## 🔗 Nodi Comuni da Abbinare + +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Ramificazione Condizionale|Giudica flusso successivo in base al risultato di esecuzione strumento| +|Nodo Chiamata Modello Grande|Utilizza risultato strumento come contesto per rispondere| +|Nodo Risposta Messaggio|Mostra direttamente all'utente il risultato della ricerca strumento| +|Nodo Salvataggio Variabili|Salva informazioni importanti restituite dallo strumento per utilizzo nodi successivi| +|Nodo Esecuzione Codice|Elabora ulteriormente e converte dati restituiti dallo strumento| + +--- + # 工具节点 ## 什么是工具节点？ diff --git a/docs/zh/tutorial/basic/node/Variable-saving.md b/docs/zh/tutorial/basic/node/Variable-saving.md index e7998ec24..6d1b2f8b2 100644 --- a/docs/zh/tutorial/basic/node/Variable-saving.md +++ b/docs/zh/tutorial/basic/node/Variable-saving.md @@ -1,3 +1,157 @@ +# 💾 Nodo Salvataggio Variabili + +## ❓ Che Cos'è il Nodo Salvataggio Variabili? + +Il nodo Salvataggio Variabili è un nodo di elaborazione dati di base in Magic Flow, utilizzato per creare, impostare o aggiornare variabili nel flusso di lavoro. Questo nodo aiuta a memorizzare dati temporanei nel flusso, per l'utilizzo nei nodi successivi, realizzando passaggio e condivisione dati tra nodi diversi. + +**Spiegazione Interfaccia:** + +L'interfaccia del nodo Salvataggio Variabili è composta da area impostazioni informazioni base variabile a sinistra e area configurazione valore variabile a destra. Qui puoi impostare nome variabile, nome visualizzato, selezionare tipo variabile e assegnare valori specifici alla variabile. +![Nodo Salvataggio Variabili](https://cdn.letsmagic.cn/static/img/Variable-saving.png) + +## 🤔 Perché Serve il Nodo Salvataggio Variabili? + +Nella costruzione di flussi di lavoro, spesso necessitiamo di memorizzare temporaneamente alcuni dati, come input utente, risultati di calcolo o stati intermedi, per utilizzarli in diverse fasi del flusso di lavoro. Il nodo Salvataggio Variabili è progettato proprio per soddisfare questa esigenza. Può: +- Creare nuove variabili o aggiornare valori di variabili esistenti +- Supportare molteplici tipi di dati, soddisfacendo diverse esigenze di memorizzazione +- Fornire supporto dati per altri nodi nel flusso di lavoro +- Realizzare passaggio e condivisione dati all'interno del flusso di lavoro + +## 🎯 Scenari Applicabili + +### Scenario 1: Memorizzazione Input Utente +Quando necessiti di registrare informazioni fornite dall'utente nella conversazione (come nome, età, preferenze, ecc.), puoi utilizzare il nodo Salvataggio Variabili per salvare queste informazioni, per l'utilizzo nei nodi successivi. + +### Scenario 2: Salvataggio Risultati di Calcolo Intermedi +In flussi di lavoro complessi, potresti necessitare di elaborazioni dati multi-step. Il nodo Salvataggio Variabili può aiutarti a memorizzare i risultati di calcolo di ogni step, evitando calcoli ripetuti. + +### Scenario 3: Controllo Dinamico Direzione Flusso di Lavoro +Puoi utilizzare il nodo Salvataggio Variabili per memorizzare flag o valori di stato, poi utilizzare questi valori variabili nel nodo ramificazione condizionale per decidere il percorso di esecuzione del flusso di lavoro. + +## ⚙️ Spiegazione Parametri del Nodo + +I parametri del nodo Salvataggio Variabili si dividono principalmente in due parti: informazioni base variabile e impostazioni valore variabile. + +### Informazioni Base Variabile +|Nome Parametro|Descrizione|Obbligatorio|Valore Esempio| +|---|---|---|---| +|Nome Variabile|Identificatore univoco della variabile, può contenere solo lettere, numeri e trattini bassi, utilizzato per riferimento della variabile in codice o altri nodi|Sì|user_name| +|Nome Visualizzato|Nome della variabile leggibile dall'uomo, rende più facile il riconoscimento nel flusso di lavoro|No|Nome Utente| +|Tipo Variabile|Tipo di dati della variabile, determina che tipo di dati può memorizzare la variabile|Sì|Stringa| +|Valore Variabile|Imposta il valore della variabile, può essere valore fisso o ottenuto da output di altri nodi|Sì|Valore Fisso| + +### Opzioni Tipo Variabile +**Il nodo Salvataggio Variabili supporta i seguenti tipi di variabile comuni:** +1. **Stringa** - Utilizzata per memorizzare contenuto testuale +2. **Numero** - Utilizzata per memorizzare interi o decimali +3. **Valore Booleano** - Utilizzata per memorizzare valori binari sì/no, vero/falso +4. **Array** - Utilizzata per memorizzare collezione di molteplici valori +5. **Oggetto** - Utilizzata per memorizzare strutture dati complesse con molteplici coppie chiave-valore + +### Impostazioni Valore Variabile +**Le modalità di impostazione del valore variabile differiscono secondo il tipo di variabile selezionato:** +- **Stringa**: Puoi input diretto testo o riferimento altre variabili +- **Numero**: Input valore numerico o espressione matematica +- **Valore Booleano**: Seleziona "Vero" o "Falso" +- **Array**: Aggiungi molteplici elementi, ogni elemento può essere di tipo diverso +- **Oggetto**: Aggiungi molteplici coppie chiave-valore, specifica nome chiave e valore per ogni proprietà + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Aggiungi Nodo**: Nell'editor del flusso di lavoro, trova il nodo "Salvataggio Variabili" dal pannello nodi a sinistra, trascinalo nella posizione appropriata del canvas del flusso di lavoro. +2. **Imposta Nome Variabile**: Nel pannello proprietà a destra, specifica un nome significativo per la variabile, si consiglia utilizzo lettere minuscole con trattini bassi, come `user_age`. +3. **Aggiungi Nome Visualizzato (Opzionale)**: Input nome facilmente comprensibile in italiano, come "Età Utente". +4. **Seleziona Tipo Variabile**: Secondo il tipo di dati da memorizzare, seleziona il tipo di variabile appropriato. +5. **Imposta Valore Variabile**: Secondo il tipo di variabile selezionato, imposta il valore specifico della variabile. +6. **Connetti Nodi**: Connetti il nodo Salvataggio Variabili con altri nodi nel flusso di lavoro, formando un flusso di elaborazione completo. + +### Tecniche Avanzate +#### Utilizzo Espressioni per Impostare Valori Variabile +Puoi utilizzare espressioni per calcolare dinamicamente valori variabile: +1. Seleziona "Espressione" come tipo valore +2. Utilizza `${nome_variabile}` per riferimento variabili esistenti +3. Combina molteplici variabili o applica calcoli semplici, come `${price} * ${quantity}` + +#### Creazione Strutture Dati Annidate +Per dati complessi: +1. Utilizza tipo oggetto per creare strutture con molteplici proprietà +2. All'interno dell'oggetto puoi annidare array o altri oggetti +3. Ad esempio creazione profilo utente: +```javascript +{ + "informazioni_base": { + "nome": "${user_name}", + "età": ${user_age} + }, + "preferenze": ["${preference1}", "${preference2}"] +} +``` + +#### Impostazione Variabile Condizionale +In combinazione con nodi ramificazione condizionale e nodi salvataggio variabili: +1. Utilizza diversi nodi salvataggio variabili in rami condizionali diversi +2. Secondo le condizioni imposta valori diversi per la stessa variabile +3. Nel flusso successivo utilizza questa variabile per prendere decisioni + +## ⚠️ Note Importanti + +### Norme Denominazione Variabili +1. **Utilizza Nomi Significativi**: I nomi variabile dovrebbero esprimere chiaramente il loro scopo, come `total_price` invece di semplice `tp` +2. **Evita Caratteri Speciali**: Utilizza solo lettere, numeri e trattini bassi +3. **Evita Parole Riservate**: Non utilizzare parole riservate JavaScript come nomi variabile +4. **Mantieni Stile Consistente**: O tutto camelCase (come `userName`), o tutto trattini bassi (come `user_name`) + +### Ambito Variabili +1. **Variabili Globali**: Le variabili create nel flusso di lavoro sono disponibili in tutto il flusso di lavoro +2. **Sovrascrittura Variabili**: Variabili omonime verranno sovrascritte dai nuovi valori, presta attenzione ad evitare sovrascritture involontarie +3. **Variabili Sottoprocesso**: Le variabili del flusso principale non vengono automaticamente passate ai sottoprocessi, necessitano passaggio parametri esplicito + +### Considerazioni Performance +1. **Evita Memorizzazione Grandi Quantità Dati**: Le variabili non sono adatte per memorizzare grandi dataset, questo potrebbe influenzare le prestazioni del flusso di lavoro +2. **Pulizia Variabili Temporanee**: Variabili temporanee non più necessarie possono essere impostate a null, liberando memoria +3. **Semplificazione Struttura Variabili**: Oggetti annidati troppo complessi potrebbero influenzare leggibilità e manutenibilità + +## ❓ Problemi Comuni + +### Problema 1: Perché la Mia Variabile Non È Accessibile in Altri Nodi? +**Soluzioni**: +1. Conferma che il nome variabile sia scritto correttamente, presta attenzione a maiuscole/minuscole +2. Verifica l'ordine di esecuzione del flusso di lavoro, assicurati che il nodo salvataggio variabili sia eseguito prima del riferimento alla variabile +3. Verifica che la sintassi di riferimento variabile sia corretta, come `${nome_variabile}` +4. Conferma che non ci siano variabili omonime sovrascritte involontariamente + +### Problema 2: Come Memorizzare Strutture Dati Complesse in una Variabile? +**Soluzioni**: +1. Utilizza tipo oggetto per creare strutture chiave-valore +2. Utilizza tipo array per memorizzare dati lista +3. All'interno dell'oggetto puoi annidare oggetti o array, creando strutture multilivello +4. Per dati molto complessi, considera l'utilizzo del nodo esecuzione codice per l'elaborazione + +### Problema 3: Come Aggiornare Elementi Specifici in una Variabile di Tipo Array? +**Soluzioni**: +1. Utilizza il nodo esecuzione codice per ottenere la variabile array +2. Modifica il valore nella posizione indice specifica +3. Utilizza il nodo salvataggio variabili per salvare l'array aggiornato +```javascript +// Nel nodo esecuzione codice +let myArray = context.variableGet("my_array", []); +myArray[2] = "nuovo_valore"; // Aggiorna elemento con indice 2 +context.variableSave("my_array", myArray); +``` + +## 🔗 Nodi Comuni da Abbinare + +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Esecuzione Codice|Effettua calcoli complessi e elaborazioni variabili| +|Nodo Ramificazione Condizionale|Prende decisioni basate sui valori delle variabili| +|Nodo Attesa|Memorizza informazioni di input utente| +|Nodo Chiamata Modello Grande|Salva risultati di elaborazione del modello grande| +|Nodo Richiesta HTTP|Memorizza dati di risposta API| + +--- + # 变量保存节点 ## 什么是变量保存节点？ diff --git a/docs/zh/tutorial/basic/node/Vector-deletion.md b/docs/zh/tutorial/basic/node/Vector-deletion.md index e14026131..4c325235e 100644 --- a/docs/zh/tutorial/basic/node/Vector-deletion.md +++ b/docs/zh/tutorial/basic/node/Vector-deletion.md @@ -1,3 +1,126 @@ +# 🗑️ Nodo Cancellazione Vettoriale + +## 🔍 Introduzione al Nodo + +Il nodo Cancellazione Vettoriale è un nodo utilizzato per rimuovere frammenti di conoscenza specifici dalla knowledge base, può aiutarti a rimuovere selettivamente contenuti di conoscenza non più necessari. Questo nodo ti permette di mantenere l'attualità e l'accuratezza della knowledge base, rimuovendo frammenti di conoscenza obsoleti, errati o ridondanti. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Cancellazione Vettoriale contiene principalmente tre parti: area selezione knowledge base, impostazioni corrispondenza metadati e area ID business. Dall'alto verso il basso puoi selezionare la knowledge base da operare, puoi impostare condizioni di cancellazione, includendo cancellazione per ID, cancellazione per parole chiave, ecc. +![Nodo Cancellazione Vettoriale](https://cdn.letsmagic.cn/static/img/Vector-deletion.png) + +## 🤔 Perché Serve il Nodo Cancellazione Vettoriale? + +**Nel processo di utilizzo della knowledge base vettoriale, con il passare del tempo, potresti incontrare le seguenti situazioni che richiedono la cancellazione di parte della conoscenza:** +- Il contenuto della conoscenza è obsoleto, necessita pulizia dati vecchi +- Sono stati importati erroneamente informazioni errate o non rilevanti, necessitano rimozione +- Regolazione struttura knowledge base, necessita cancellazione contenuti duplicati o ridondanti +- Informazioni privacy o sensibili necessitano rimozione dalla knowledge base +- La capacità della knowledge base si avvicina al limite, necessita cancellazione contenuti a basso valore +Il nodo Cancellazione Vettoriale fornisce capacità di cancellazione precisa, può rimuovere selettivamente frammenti di conoscenza specifici senza influenzare altri contenuti di conoscenza, mantenendo qualità e prestazioni della knowledge base. + +## 🎯 Scenari Applicabili + +### Scenario 1: Manutenzione Aggiornamento Contenuti +Quando i tuoi documenti business hanno aggiornamenti, puoi prima cancellare i frammenti di conoscenza della versione precedente, poi importare il contenuto della nuova versione, assicurando che le informazioni nella knowledge base mantengano sempre l'ultima versione. + +### Scenario 2: Correzione Contenuti Errati +Quando scopri che nella knowledge base esistono informazioni errate o inaccurate, puoi utilizzare il nodo Cancellazione Vettoriale per rimuovere precisamente questi contenuti, evitando di influenzare l'esperienza utente. + +### Scenario 3: Riorganizzazione e Pulizia Knowledge Base +Quando necessiti di riorganizzare o ripulire la knowledge base, puoi prima cancellare contenuti di categorie specifiche, poi reimportare strutture di conoscenza più ordinate. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri di Input +|Nome Parametro|Descrizione|Obbligatorio|Tipo Parametro| +|---|---|---|---| +|Selezione Knowledge Base|Scegli la knowledge base da operare, attraverso 【Valore Fisso o Espressione】, seleziona dalla knowledge base già create nel sistema|Sì|Selezione Dropdown| +|Modalità Cancellazione|Quando selezioni "Cancellazione per ID Business", attraverso aggiunta variabile, cancella i dati della knowledge base specificata. Quando selezioni "Cancellazione per Condizione", attraverso espressione imposta condizioni di filtro, come parole chiave, intervallo temporale, ecc.|Sì|Scelta Binaria| + +### Parametri di Output +Il nodo Cancellazione Vettoriale dopo esecuzione riuscita, completerà la cancellazione dei contenuti in background, ma non restituirà direttamente dati risultato specifici. Dopo cancellazione riuscita, il contenuto può essere confermato attraverso ricerca tramite il nodo Ricerca Vettoriale. + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Selezione Knowledge Base**: + 1. Dal menu dropdown seleziona modalità diverse + 2. Attraverso @ riferimento dinamico alla knowledge base del nodo precedente oppure knowledge base già create +2. **Selezione Modalità Cancellazione**: + 1. Se selezioni "Cancellazione per ID", inserisci gli ID da cancellare nel campo "Lista ID Frammenti", ID multipli separati da virgola + 2. Se selezioni "Cancellazione per Condizione", imposta condizioni di filtro, come frammenti contenenti parole chiave specifiche +3. **Connessione Nodi**: Connetti il nodo Cancellazione Vettoriale con nodi upstream (che forniscono condizioni di cancellazione) e nodi downstream (che elaborano risultati di cancellazione) + +### Tecniche Avanzate +1. **Utilizzo Variabili per Specificare Dinamicamente ID**: Puoi utilizzare variabili di output del nodo upstream come condizioni di cancellazione, realizzando cancellazione dinamica. Ad esempio, attraverso il nodo "Esecuzione Codice" filtra la lista ID da cancellare, passandola al nodo Cancellazione Vettoriale. +2. **Cancellazione Condizionale Batch**: Quando necessiti di ripulire grandi quantità di dati che soddisfano condizioni specifiche, puoi utilizzare la funzionalità di cancellazione condizionale in combinazione con molteplici condizioni (come intervallo temporale + parole chiave), migliorando l'efficienza. +3. **Utilizzo in Combinazione con Nodo Ciclo**: Per scenari di cancellazione complessi, puoi combinare con il nodo ciclo per realizzare cancellazione a lotti, evitando problemi di timeout causati da cancellazione eccessiva in una volta sola. + +## ⚠️ Note Importanti + +### Operazione di Cancellazione Irreversibile +Una volta eseguita l'operazione di cancellazione, i dati dei frammenti di conoscenza cancellati **non potranno essere recuperati**. Pertanto, prima di effettuare cancellazioni batch, si consiglia di: +- Esportare backup dei frammenti di conoscenza correlati +- Utilizzare test su piccola scala per verificare l'accuratezza delle condizioni di cancellazione +- Assicurarsi che l'operazione di cancellazione abbia chiare esigenze business + +### Impatto sulle Prestazioni +Operazioni di cancellazione su larga scala potrebbero influenzare le prestazioni del sistema, presta attenzione a: +- Evitare di effettuare operazioni di cancellazione massiva durante i picchi di business +- Per knowledge base di grandi dimensioni, si consiglia cancellazione a lotti invece di cancellazione totale in una volta +- Dopo l'operazione di cancellazione, l'indice vettoriale della knowledge base necessita di tempo per la ricostruzione, durante questo periodo le prestazioni di ricerca potrebbero essere influenzate + +### Limitazioni di Autorizzazione +L'esecuzione dell'operazione di cancellazione vettoriale necessita delle corrispondenti autorizzazioni, assicurati di: +- Il creatore del flusso di lavoro abbia autorizzazioni di gestione della knowledge base +- L'operazione di cancellazione sia conforme alle normative di gestione dati aziendali +- Operazioni di cancellazione su knowledge base critiche dovrebbero impostare appropriati flussi di approvazione + +## ❓ Problemi Comuni + +### L'Operazione di Cancellazione È Eseguita con Successo ma i Risultati di Ricerca della Knowledge Base Non Sono Aggiornati +**Problema**: L'operazione di cancellazione mostra successo, ma attraverso il nodo Ricerca Vettoriale è ancora possibile ricercare i contenuti cancellati. + +**Soluzioni**: +- L'aggiornamento dell'indice della knowledge base vettoriale ha un certo ritardo, solitamente necessita di 1-5 minuti per completare il refresh dell'indice +- Se non si aggiorna da molto tempo, puoi provare ad aggiungere un appropriato nodo di attesa dopo il nodo di cancellazione +- Verifica se esistano contenuti duplicati, assicurati che le condizioni di cancellazione coprano tutti i contenuti da cancellare + +### Errore di Timeout durante Cancellazione Batch +**Problema**: Durante la cancellazione di grandi quantità di frammenti di conoscenza, il nodo va in timeout o dà errore. + +**Soluzioni**: +- Suddividi la cancellazione batch di grandi dimensioni in molteplici operazioni di piccoli lotti +- Utilizza il nodo ciclo per realizzare cancellazione a lotti +- Aumenta l'impostazione del timeout di esecuzione del nodo (se disponibile questa opzione) +- Seleziona orari con carico di sistema più basso per eseguire cancellazioni batch di grandi dimensioni + +### Impossibile Cancellare Frammenti di Conoscenza Specifici +**Problema**: Alcuni frammenti di conoscenza non possono essere cancellati, anche fornendo l'ID corretto. + +**Soluzioni**: +- Verifica se il frammento di conoscenza abbia marcatori di protezione speciali +- Conferma che l'account operativo abbia sufficienti autorizzazioni +- Verifica che l'ID del frammento di conoscenza sia corretto (presta attenzione al formato ID e maiuscole/minuscole) +- Prova ad utilizzare la modalità di cancellazione condizionale come soluzione alternativa + +## 🏆 Migliori Pratiche + +### Nodi Comuni da Abbinare + +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Ricerca Vettoriale|Prima conferma attraverso ricerca vettoriale i contenuti da cancellare, poi procedi alla cancellazione| +|Nodo Esecuzione Codice|Utilizzato per elaborare logica di condizioni di cancellazione complesse o formattare liste ID di cancellazione| +|Nodo Ramificazione Condizionale|Giudica il flusso successivo in base al risultato di cancellazione| +|Nodo Ciclo|Realizza cancellazione a lotti di grandi quantità di dati| +|Nodo Archiviazione Vettoriale|Dopo la cancellazione dei contenuti vecchi, archivia contenuti aggiornati| + +Nota: L'operazione di cancellazione sebbene semplice è irreversibile, utilizza con cautela dopo aver pienamente compreso l'impatto dell'operazione. La manutenzione e l'aggiornamento periodici della knowledge base manterranno le tue applicazioni intelligenti sempre nel migliore stato + +--- + # 向量删除节点 ## 一、节点介绍 向量删除节点是一个用于从知识库中移除特定知识片段的节点，它可以帮助您有选择地移除不再需要的知识内容。这个节点使您能够维护知识库的时效性和准确性，移除过时、错误或冗余的知识片段。 diff --git a/docs/zh/tutorial/basic/node/Vector-knowledge-base-matching.md b/docs/zh/tutorial/basic/node/Vector-knowledge-base-matching.md index 871914d34..a943d5f98 100644 --- a/docs/zh/tutorial/basic/node/Vector-knowledge-base-matching.md +++ b/docs/zh/tutorial/basic/node/Vector-knowledge-base-matching.md @@ -1,3 +1,149 @@ +# 🔍 Nodo Corrispondenza Knowledge Base Vettoriale + +## ❓ Che Cos'è il Nodo Corrispondenza Knowledge Base Vettoriale? + +Il nodo Corrispondenza Knowledge Base Vettoriale è un nodo specializzato nel flusso di lavoro Magic Flow per recuperare e abbinare contenuti della knowledge base vettoriale. Può aiutarti a filtrare le knowledge base vettoriali necessarie in base a condizioni specifiche, fornendo supporto di base per operazioni successive (come ricerca di similarità, domande e risposte sulla conoscenza, ecc.). In parole semplici, questo nodo è come filtrare gli "scaffali" appropriati nella tua knowledge base vettoriale, per poter successivamente cercare informazioni rilevanti su questi "scaffali". + +**Spiegazione Immagine:** + +L'interfaccia del nodo Corrispondenza Knowledge Base Vettoriale è composta principalmente da due parti - l'area "Configurazione Condizioni di Filtro" in alto, utilizzata per impostare le condizioni di filtro delle knowledge base vettoriali; l'area "Output" in basso, che mostra la lista delle knowledge base vettoriali filtrate. Le condizioni di filtro supportano molteplici modalità di abbinamento come uguale, diverso, contiene, non contiene per ID o nome. +![Nodo Inizio](https://cdn.letsmagic.cn/static/img/Vector-knowledge-base-matching.png) + +## 🤔 Perché Serve il Nodo Corrispondenza Knowledge Base Vettoriale? + +**Nel processo di costruzione di applicazioni intelligenti, il nodo Corrispondenza Knowledge Base Vettoriale svolge il ruolo di "filtro della conoscenza", può aiutarti a:** +- **Localizzare Precisamente le Fonti di Conoscenza**: Filtrare knowledge base vettoriali che soddisfano condizioni specifiche da molteplici knowledge base +- **Migliorare l'Efficienza di Ricerca**: Ridurre l'ambito della ricerca vettoriale successiva, migliorando precisione e velocità di ricerca +- **Selezionare Dinamicamente Knowledge Base**: Secondo scenari diversi o esigenze degli utenti, selezionare dinamicamente knowledge base appropriate +- **Filtro Combinato Multi-Condizioni**: Supportare combinazione multi-condizioni per realizzare logica di abbinamento knowledge base complessa +- **Fornire Dati ai Nodi Downstream**: Fornire la lista delle knowledge base filtrate ai successivi nodi di ricerca vettoriale + +## 🎯 Scenari Applicabili + +### 1. Sistema di Domande e Risposte Intelligente Multi-Dominio +Quando costruisci un sistema di domande e risposte che copre molteplici domini, puoi prima utilizzare il nodo Corrispondenza Knowledge Base Vettoriale per filtrare le knowledge base relative al dominio delle domande dell'utente, poi procedere con la ricerca precisa dei contenuti, migliorando l'accuratezza delle risposte. + +### 2. Ricerca di Conoscenza con Controllo Permessi +All'interno dell'azienda, diversi dipartimenti o ruoli potrebbero avere il diritto di accedere a knowledge base diverse. Attraverso il nodo Corrispondenza Knowledge Base Vettoriale, puoi filtrare le knowledge base che l'utente ha il diritto di accedere in base alle informazioni di dipartimento o ruolo dell'utente, assicurando la sicurezza delle informazioni. + +### 3. Ricerca Collaborativa Multi-Knowledge Base +Quando necessiti di effettuare ricerca collaborativa in molteplici knowledge base correlate, puoi prima utilizzare il nodo Corrispondenza Knowledge Base Vettoriale per filtrare queste knowledge base correlate, poi effettuare ricerca unificata in queste knowledge base, ottenendo informazioni più complete. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri Base +|Nome Parametro|Descrizione|Obbligatorio|Valore Default| +|---|---|---|---| +|Condizioni di Ricerca|Imposta la combinazione di condizioni per ricercare knowledge base vettoriali|Sì|Nessuno| + +### Dettagli Condizioni di Ricerca +|Componenti Condizione|Valori Opzionali|Descrizione| +|---|---|---| +|Tipo Valore Sinistro|ID Knowledge Base|Filtra per identificatore univoco knowledge base| +||Nome Knowledge Base|Filtra per nome knowledge base| +|Operatore|Uguale|Abbinamento completo al valore specificato| +||Diverso|Esclude risultati che corrispondono completamente al valore specificato| +||Contiene|Contiene la stringa specificata| +||Non Contiene|Non contiene la stringa specificata| +|Valore Destro|Input Personalizzato|Inserisci il valore di filtro specifico, può essere ID o nome (dipende dal tipo valore sinistro)| + +### Contenuto Output +|Campo Output|Descrizione| +|---|---| +|Lista Knowledge Base Vettoriali (vector_databases)|Lista delle knowledge base vettoriali filtrate, contiene ID e nome di ciascuna knowledge base| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Aggiungere Condizioni di Ricerca**: + 1. Clicca il pulsante "Aggiungi Condizione" per aggiungere una condizione di filtro + 2. Dal menu dropdown tipo valore sinistro seleziona "ID Knowledge Base" o "Nome Knowledge Base" + 3. Seleziona l'operatore appropriato (uguale, diverso, contiene, non contiene) + 4. Nel campo input valore destro inserisci il valore di filtro specifico +2. **Impostare Molteplici Condizioni (Opzionale)**: + 1. Se necessiti di impostare molteplici condizioni, ripeti cliccando il pulsante "Aggiungi Condizione" + 2. Tra molteplici condizioni puoi scegliere relazione "E" o "O" +3. **Combinazione Condizioni (Opzionale)**: + 1. Per logica di filtro complessa, puoi creare gruppi di condizioni + 2. Clicca il pulsante "Aggiungi Gruppo Condizioni" per creare un nuovo gruppo di condizioni + 3. Nel gruppo di condizioni aggiungi condizioni e imposta relazioni tra condizioni +4. **Anteprima Output**: + 1. Dopo la configurazione, puoi visualizzare in anteprima la lista delle knowledge base vettoriali filtrate nella sezione output del nodo + +### Tecniche Avanzate +#### Strategie di Ricerca Efficienti +1. **Filtro Preciso**: Quando conosci chiaramente l'ID o il nome completo della knowledge base target, utilizza l'operatore "Uguale" per abbinamento preciso +2. **Filtro Fuzzy**: Quando conosci solo parte delle informazioni del nome della knowledge base, utilizza l'operatore "Contiene" per abbinamento fuzzy +3. **Strategia di Esclusione**: Utilizza gli operatori "Diverso" o "Non Contiene" per escludere knowledge base non necessarie + +#### Collaborazione con Altri Nodi +**Il nodo Corrispondenza Knowledge Base Vettoriale necessita solitamente di essere utilizzato in combinazione con altri nodi:** +1. **In Combinazione con Nodo Ricerca Vettoriale**: + 1. Utilizza il nodo Corrispondenza Knowledge Base Vettoriale per filtrare knowledge base rilevanti + 2. Poi utilizza il nodo Ricerca Vettoriale per effettuare ricerca di similarità dei contenuti in queste knowledge base +2. **In Combinazione con Nodo Ramificazione Condizionale**: + 1. Secondo se i risultati di filtro sono vuoti decide il flusso successivo + 2. Puoi impostare soluzioni di backup quando non vengono trovate knowledge base corrispondenti +3. **In Combinazione con Nodo Chiamata Modello Grande**: + 1. Passa le informazioni delle knowledge base filtrate al modello grande + 2. Fa sì che il modello grande generi risposte basate su queste knowledge base specifiche + +## ⚠️ Note Importanti + +### Limitazioni di Autorizzazione +Il nodo può filtrare solo le knowledge base vettoriali che l'utente corrente ha il permesso di accedere: +- Le knowledge base senza permesso di accesso non appariranno nei risultati di filtro, anche se soddisfano le condizioni di filtro +- Assicurati che il creatore del flusso abbia permessi di lettura sulle knowledge base rilevanti + +### Considerazioni sulle Prestazioni +Quando il numero di knowledge base è elevato, condizioni di filtro complesse potrebbero influenzare l'efficienza di esecuzione: +- Cerca di utilizzare condizioni di filtro precise +- Evita di utilizzare troppi operatori "Contiene" o "Non Contiene" +- Riduci il più possibile i livelli di annidamento dei gruppi di condizioni + +### Gestione Risultati Vuoti +Se le condizioni di filtro sono troppo restrittive, potrebbero portare a nessuna knowledge base che soddisfa le condizioni: +- Assicurati di gestire nel flusso i possibili casi di risultati vuoti +- Considera di utilizzare il nodo Ramificazione Condizionale per verificare se i risultati di filtro sono vuoti + +## ❓ Problemi Comuni + +### Problema 1: Dopo la ricerca non viene restituita alcuna knowledge base, ma sono sicuro che esistono knowledge base che soddisfano le condizioni, quale potrebbe essere la causa? + +**Soluzioni**: Le possibili cause includono: +- Problema di permessi: Potresti non avere il permesso di accedere a queste knowledge base +- Impostazione condizioni errata: Verifica che l'ortografia, maiuscole/minuscole delle condizioni di filtro siano corrette +- Stato knowledge base: La knowledge base target potrebbe essere disabilitata o eliminata + +### Problema 2: Come filtrare contemporaneamente per ID e nome delle knowledge base? + +**Soluzioni**: Puoi aggiungere molteplici condizioni di filtro: +- Aggiungi la prima condizione, seleziona "ID Knowledge Base" come tipo valore sinistro, imposta operatore e valore destro corrispondenti +- Clicca "Aggiungi Condizione" per aggiungere la seconda condizione +- Seleziona "Nome Knowledge Base" come tipo valore sinistro, imposta operatore e valore destro corrispondenti +- Tra le due condizioni scegli la relazione "E" o "O" + +### Problema 3: Come utilizzare la lista delle knowledge base vettoriali in output del nodo nei nodi successivi? + +**Soluzioni**: La lista delle knowledge base vettoriali in output può essere utilizzata nei nodi successivi attraverso riferimento variabile: +- Nel nodo Ricerca Vettoriale, puoi referenziare `output_nodo_precedente.vector_databases` +- Se necessiti di ottenere l'ID di una knowledge base specifica, puoi utilizzare `output_nodo_precedente.vector_databases[0].id` +- Nel nodo Esecuzione Codice, puoi accedere e elaborare questi dati attraverso JavaScript + +## 🏆 Migliori Pratiche + +### Nodi Comuni da Abbinare + +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Ricerca Vettoriale|Effettua ricerca di similarità dei contenuti nelle knowledge base filtrate| +|Nodo Ramificazione Condizionale|Decide il flusso di elaborazione successivo in base ai risultati di filtro| +|Nodo Chiamata Modello Grande|Utilizza le knowledge base filtrate per domande e risposte con arricchimento di conoscenza| +|Nodo Salvataggio Variabili|Salva i risultati di filtro per utilizzo in molteplici nodi successivi| +|Nodo Esecuzione Codice|Effettua elaborazione o conversione avanzata dei risultati di filtro| + +--- + # 向量知识库匹配节点 ## 什么是向量知识库匹配节点？ 向量知识库匹配节点是 Magic Flow 工作流中专门用于检索和匹配向量知识库内容的节点。它能帮助您根据特定条件筛选出需要的向量知识库，为后续的相关操作（如相似度搜索、知识问答等）提供基础支持。简单来说，这个节点就像是在您的向量知识库中筛选出合适的"书架"，以便后续可以在这些"书架"上查找相关信息。 diff --git a/docs/zh/tutorial/basic/node/Vector-search.md b/docs/zh/tutorial/basic/node/Vector-search.md index 8bbd97c14..bc3f5bf47 100644 --- a/docs/zh/tutorial/basic/node/Vector-search.md +++ b/docs/zh/tutorial/basic/node/Vector-search.md @@ -1,3 +1,150 @@ +# 🔍 Nodo Ricerca Vettoriale + +## ❓ Che Cos'è il Nodo Ricerca Vettoriale? + +Il nodo Ricerca Vettoriale è un nodo funzionale nel flusso di lavoro Magic Flow utilizzato per ricercare rapidamente contenuti simili nel database vettoriale. Può trovare frammenti di contenuto semanticamente simili nella knowledge base pre-memorizzata in base al testo di query fornito dall'utente. In parole semplici, la ricerca vettoriale è come un motore di ricerca intelligente che non solo trova contenuti contenenti parole chiave, ma comprende anche la semantica della domanda e restituisce informazioni rilevanti. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Ricerca Vettoriale mostra l'area di configurazione principale del nodo, includendo selezione knowledge base, input testo di query, impostazione soglia similarità e limitazione numero risultati e altre opzioni di configurazione parametri. +![Nodo Ricerca Vettoriale](https://cdn.letsmagic.cn/static/img/Vector-search.png) + +## 🤔 Perché Serve il Nodo Ricerca Vettoriale? + +**Nella costruzione di applicazioni intelligenti, il nodo Ricerca Vettoriale risolve il problema di trovare informazioni precise da grandi quantità di dati non strutturati:** +- **Comprensione Semantica**: Basata su semantica piuttosto che semplice abbinamento di parole chiave, può comprendere la vera intenzione della domanda dell'utente +- **Recupero Informazioni**: Trova rapidamente i frammenti di contenuto più rilevanti da documenti e knowledge base di massa +- **Supporto Conoscenza**: Fornisce al modello grande conoscenze professionali accurate e informazioni di background, migliorando la qualità delle risposte +- **Conoscenza Personalizzata**: Utilizza dati specifici dell'azienda per costruire capacità di domanda e risposta dedicate, risolvendo il problema della conoscenza limitata dei modelli generici +- **Elaborazione Efficiente**: Riduce la quantità di informazioni elaborate dal modello grande, migliora la velocità di risposta, risparmia consumo di token + +## 🎯 Scenari Applicabili + +### 1. Sistema di Domande e Risposte Knowledge Base Aziendale +Costruisci sistema di domande e risposte basato su documenti interni aziendali, manuali prodotto o documentazione tecnica, i dipendenti possono porre domande in linguaggio naturale per ottenere risposte precise, senza dover sfogliare numerosi file. + +### 2. Assistente Clienti Intelligente +Fornisci all'assistente clienti supporto di conoscenza come informazioni prodotto, soluzioni a problemi comuni, ecc., aiutando il personale di assistenza clienti o chatbot a rispondere rapidamente e accuratamente alle domande dei clienti. + +### 3. Analisi Documenti ed Estrazione Informazioni +Estrai informazioni specifiche da numerosi documenti, come termini contrattuali, specifiche tecniche o dati chiave nei rapporti di ricerca, risparmiando tempo di ricerca manuale. + +## ⚙️ Spiegazione Parametri del Nodo + +### Parametri Base +|Nome Parametro|Descrizione|Obbligatorio|Valore Default| +|---|---|---|---| +|Selezione Knowledge Base|Scegli la knowledge base da operare, attraverso 【Valore Fisso o Espressione】, seleziona dalla knowledge base già create nel sistema|Sì|Nessuno| +|Parole Chiave Ricerca|Testo utilizzato per ricercare contenuti simili, solitamente una domanda o descrizione chiave|Sì|Nessuno| +|Numero Massimo Richiami|Limite superiore del numero di contenuti simili restituiti|No|5| +|Similarità Minima|Requisito minimo di similarità dei contenuti, range 0-1, valore più alto significa requisito più severo|No|0.4| +|Abbinamento Metadati|Filtra in base alle informazioni metadati del documento, come fonte documento, tempo creazione, ecc.|No|-| + +### Contenuto Output +|Campo Output|Descrizione|Tipo| +|---|---|---| +|Set Risultati Richiamo (similarities)|Array dei contenuti simili trovati, contiene tutti i frammenti di testo corrispondenti|Array Stringhe| +|Lista Frammenti (fragments)|Informazioni complete dei risultati di ricerca, contiene contenuto, metadati e ID business ecc.|Array Oggetti| + +## 📋 Istruzioni per l'Uso + +### Passi di Configurazione Base +1. **Selezione Knowledge Base**: + 1. Dal menu dropdown seleziona modalità diverse + 2. Attraverso @ riferimento dinamico alla knowledge base del nodo precedente oppure knowledge base già create +2. **Configurazione Parole Chiave**: + 1. Inserisci testo di ricerca fisso + 2. Oppure utilizza riferimento variabile per contenuto dinamico, come `{{user_message}}` per referenziare la domanda effettiva dell'utente +3. **Impostazione Numero Massimo Risultati Richiamo**: + 1. Imposta il limite superiore del numero di risultati restituiti secondo le esigenze + 2. Generalmente si consiglia 5-10 risultati, troppi potrebbero introdurre informazioni irrilevanti, troppo pochi potrebbero omettere contenuti importanti +4. **Regolazione Soglia Similarità**: + 1. Imposta la soglia di similarità per controllare la precisione dei risultati + 2. Soglia più alta significa risultati più precisi ma potrebbe omettere contenuti rilevanti + 3. Soglia più bassa significa copertura più ampia ma potrebbe includere contenuti non molto rilevanti +5. **Configurazione Filtro Metadati (Opzionale)**: + 1. Se necessiti di filtrare ulteriormente i risultati, puoi impostare condizioni di filtro metadati + 2. Ad esempio, limita documenti di fonte specifica o range temporale + +### Tecniche Avanzate +#### Ottimizzazione Testo di Ricerca +La chiave per migliorare l'effetto della ricerca vettoriale è scrivere testo di query efficace: +1. **Specifico e Chiaro**: Utilizza descrizioni chiare e specifiche, non formulazioni vaghe +2. **Informazioni Chiave Prioritarie**: Posiziona le parole chiave e i concetti più importanti all'inizio del testo di query +3. **Evita Informazioni Irrilevanti**: Semplifica il testo di query, elimina parole che non aiutano la ricerca + +#### Collaborazione con Altri Nodi +Il nodo Ricerca Vettoriale necessita solitamente di essere utilizzato in combinazione con altri nodi: +1. **In Combinazione con Nodo Chiamata Modello Grande**: + 1. Fornisci i risultati della ricerca vettoriale come contesto al modello grande + 2. Utilizza il nodo Esecuzione Codice per elaborare i risultati di ricerca, poi passali al modello grande +2. **In Combinazione con Nodo Ramificazione Condizionale**: + 1. Verifica se i risultati di ricerca sono vuoti + 2. Secondo numero risultati o similarità decide la modalità di elaborazione successiva +3. **In Combinazione con Nodo Segmentazione Testo**: + 1. Prima utilizza il nodo Segmentazione Testo per elaborare testi lunghi + 2. Poi effettua memorizzazione vettoriale e ricerca sui frammenti segmentati + +## ⚠️ Note Importanti + +### Preparazione Knowledge Base Vettoriale +**Prima di utilizzare il nodo Ricerca Vettoriale, è necessario preparare la knowledge base vettoriale:** +- Assicurati di aver creato e importato i documenti di conoscenza rilevanti +- Verifica lo stato di aggiornamento della knowledge base vettoriale, assicurati che i dati siano aggiornati +- Per knowledge base di grandi dimensioni, considera una classificazione ragionevole per migliorare la precisione di ricerca + +### Lunghezza Testo Query +**La lunghezza del testo di query influenza l'effetto di ricerca:** +- Query troppo brevi potrebbero mancare di informazioni sufficienti per abbinamento accurato +- Query troppo lunghe potrebbero introdurre rumore, diluendo il peso delle parole chiave core +- Si consiglia di mantenere il testo di query tra 20-100 caratteri + +### Ottimizzazione Soglia Similarità +**La soglia di similarità necessita di essere regolata secondo lo scenario applicativo specifico:** +- Domande e risposte generiche: si consiglia di utilizzare soglia 0.4-0.6 +- Ricerca conoscenza professionale: può essere aumentata a 0.6-0.8 per assicurare accuratezza +- Ricerca esplorativa: può essere diminuita a 0.3-0.5 per ottenere più informazioni rilevanti + +## ❓ Problemi Comuni + +### Problema 1: I risultati di ricerca non corrispondono alle aspettative, come fare? + +**Soluzioni**: +- Verifica se il contenuto della knowledge base include informazioni rilevanti +- Prova a riscrivere il testo di query, utilizzando descrizioni più precise +- Abbassa la soglia di similarità per ottenere risultati più ampi +- Utilizza filtro metadati per restringere l'ambito di ricerca + +### Problema 2: Come gestire il caso in cui i risultati di ricerca sono vuoti? + +**Soluzioni**: +- Aggiungi nel flusso di lavoro una ramificazione condizionale per rilevare il numero di risultati +- Imposta risposta di backup o conoscenza predefinita +- Abbassa la soglia di similarità, allenta le condizioni di abbinamento +- Utilizza testo di query più generico per ricercare nuovamente + +### Problema 3: La velocità di ricerca è lenta, come ottimizzare? + +**Soluzioni**: +- Riduci il numero di knowledge base da ricercare, seleziona solo quelle più rilevanti +- Ottimizza la struttura della knowledge base, evita librerie singole troppo grandi +- Riduci il limite del numero di risultati restituiti +- Utilizza filtro metadati per restringere l'ambito di ricerca + +## 🏆 Migliori Pratiche + +### Nodi Comuni da Abbinare + +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Chiamata Modello Grande|Utilizza i risultati di ricerca per fornire supporto di conoscenza professionale al modello grande| +|Nodo Esecuzione Codice|Elabora e converte i risultati di ricerca, estrae informazioni chiave| +|Nodo Ramificazione Condizionale|Decide il flusso successivo in base ai risultati di ricerca| +|Nodo Segmentazione Testo|Elabora testi lunghi, prepara memorizzazione vettoriale o ricerca| +|Nodo Memorizzazione Vettoriale|In combinazione con ricerca vettoriale, realizza aggiornamento e ricerca della knowledge base| + +--- + # 向量搜索节点 ## 什么是向量搜索节点？ 向量搜索节点是Magic Flow工作流中用于在向量数据库中快速检索相似内容的功能节点。它能够根据用户提供的查询文本，在预先存储的知识库中找出语义相似的内容片段。简单来说，向量搜索就像是一个智能搜索引擎，不仅能找到包含关键词的内容，还能理解问题的语义并返回相关信息。 diff --git a/docs/zh/tutorial/basic/node/Vector-storage.md b/docs/zh/tutorial/basic/node/Vector-storage.md index 4bf9f1f6b..9667e0619 100644 --- a/docs/zh/tutorial/basic/node/Vector-storage.md +++ b/docs/zh/tutorial/basic/node/Vector-storage.md @@ -1,3 +1,144 @@ +# 🔒 Nodo Memorizzazione Vettoriale +## ❓ Che Cos'è il Nodo Memorizzazione Vettoriale? +Il nodo Memorizzazione Vettoriale è un componente funzionale nel flusso di lavoro Magic Flow utilizzato per memorizzare il contenuto testuale nel database vettoriale. Può convertire il contenuto testuale in forma vettoriale e salvarlo nella knowledge base, facilitando la ricerca semantica e l'abbinamento dei contenuti successivi. In parole semplici, la memorizzazione vettoriale è come un magazzino di informazioni intelligente, non solo memorizza il contenuto stesso, ma conserva anche le caratteristiche semantiche del contenuto, rendendo possibile la query tramite similarità semantica successivamente. + +**Spiegazione Immagine:** + +L'interfaccia del nodo Memorizzazione Vettoriale mostra l'area principale di configurazione del nodo, includendo selezione knowledge base, input del contenuto da memorizzare, impostazioni metadati e configurazione ID business e altre opzioni di impostazione parametri +![Nodo Inizio](https://cdn.letsmagic.cn/static/img/Vector-storage.png) + +## 🤔 Perché Serve il Nodo Memorizzazione Vettoriale? +**Nella costruzione di applicazioni intelligenti, il nodo Memorizzazione Vettoriale risolve i seguenti problemi chiave:** +- **Sedimentazione della Conoscenza**: Trasforma informazioni importanti in conoscenza ricercabile, costruisce knowledge base dedicate all'azienda +- **Comprensione Semantica**: Diverso dai database tradizionali, la memorizzazione vettoriale conserva le informazioni semantiche del contenuto, supporta ricerca per similarità +- **Organizzazione Informazioni**: Attraverso metadati e ID business, classifica e gestisce i contenuti memorizzati +- **Conoscenza Personalizzata**: Fornisce al modello grande supporto di conoscenza dedicato, risolvendo il problema della conoscenza limitata dei modelli generici +- **Base per Applicazioni Intelligenti**: Fornisce base dati per sistemi di domanda e risposta, sistemi di raccomandazione e altre applicazioni intelligenti + +## 🎯 Scenari Applicabili + +### 1. Costruzione di Knowledge Base Aziendale +Memorizza contenuti come documenti aziendali, manuali prodotto, guide operative nel database vettoriale, formando un sistema di conoscenza aziendale ricercabile, aiutando i dipendenti a ottenere rapidamente le informazioni necessarie. + +### 2. Accumulo Conoscenza per Servizio Clienti Intelligente +Memorizza soluzioni a problemi comuni, informazioni prodotto, processi di servizio e altri contenuti, fornendo supporto di conoscenza ai chatbot, migliorando la qualità del servizio clienti. + +### 3. Gestione Contenuti Personalizzata +Memorizza preferenze utente, cronologia interazioni e altre informazioni, fornendo supporto dati per raccomandazioni e servizi personalizzati, migliorando l'esperienza utente. + +## ⚙️ Spiegazione Parametri del Nodo +### Parametri Base +|Nome Parametro|Descrizione|Obbligatorio|Valore Default| +|---|---|---|---| +|Selezione Knowledge Base|Scegli la knowledge base da operare, attraverso 【Valore Fisso o Espressione】, seleziona dalla knowledge base già create nel sistema|Sì|Nessuno| +|Contenuto da Memorizzare|Contenuto testuale da memorizzare nel database vettoriale|Sì|Nessuno| +|ID Business|Identificatore univoco del contenuto, utilizzato per query o operazioni di cancellazione successive|Sì|Nessuno| +|Metadati|Informazioni aggiuntive del contenuto, come categoria, fonte, tempo, ecc., facilitano il filtraggio|No|Nessuno| + + +### Contenuto Output +Dopo esecuzione riuscita, il nodo Memorizzazione Vettoriale completerà la memorizzazione dei contenuti in background, ma non restituirà direttamente dati risultato specifici. Dopo memorizzazione riuscita, il contenuto può essere ricercato attraverso il nodo Ricerca Vettoriale. + +## 📋 Istruzioni per l'Uso +### Passi di Configurazione Base +1. **Selezione Knowledge Base**: + 1. Dal menu dropdown seleziona modalità diverse + 2. Attraverso @ riferimento dinamico alla knowledge base del nodo precedente oppure knowledge base già create +2. **Configurazione Frammenti da Memorizzare**: + 1. Inserisci il contenuto testuale da memorizzare + 2. Oppure utilizza riferimento variabile per contenuto dinamico, come `{{message_content}}` per referenziare l'output di altri nodi +3. **Impostazione ID Business**: + 1. Inserisci un identificatore di business univoco + 2. Si consiglia di utilizzare modalità di identificazione significative, come "FAQ_Prodotto_001" o UUID generato dinamicamente + 3. L'ID business è molto importante nelle operazioni di cancellazione o aggiornamento successive +4. **Configurazione Metadati (Opzionale)**: + 1. Aggiungi informazioni aggiuntive come categoria, tag, fonte del contenuto + 2. I metadati sono coppie chiave-valore, come "category: FAQ", "source: sito ufficiale" + 3. I metadati possono essere utilizzati come condizioni di filtro durante la ricerca vettoriale + +### Tecniche Avanzate +#### Ottimizzazione Contenuto +**Per migliorare l'effetto della memorizzazione vettoriale e della ricerca successiva, si consiglia di ottimizzare adeguatamente il contenuto memorizzato:** +1. **Memorizzazione a Blocchi del Contenuto**: + 1. Suddividi testi lunghi in blocchi di contenuto indipendenti più piccoli prima di memorizzarli + 2. Utilizza il nodo Segmentazione Testo per elaborare testi lunghi prima di memorizzarli + 3. Si consiglia di controllare ogni blocco di contenuto tra 500-1000 caratteri +2. **Controllo Qualità Contenuto**: + 1. Assicurati che il contenuto memorizzato sia semanticamente chiaro ed espresso accuratamente + 2. Rimuovi simboli di formattazione inutili e contenuti ridondanti + 3. Aggiungi adeguate informazioni di contesto per migliorare la comprensibilità +3. **Progettazione Metadati**: + 1. Progetta strutture metadati ragionevoli per facilitare filtri successivi + 2. Metadati comuni includono: categoria (category), fonte (source), tempo (time), ecc. + 3. Utilizza formati e convenzioni di denominazione unificati + +#### Collaborazione con Altri Nodi +**Il nodo Memorizzazione Vettoriale necessita solitamente di essere utilizzato in combinazione con altri nodi:** +1. **In Combinazione con Nodo Segmentazione Testo**: + 1. Segmenta prima il testo lungo in frammenti adatti alla memorizzazione + 2. Poi memorizza in ciclo ogni frammento segmentato + 3. Mantieni l'associazione dell'ID business, come utilizzare prefisso + numero indice +2. **In Combinazione con Nodo Esecuzione Codice**: + 1. Utilizza il nodo Esecuzione Codice per generare ID business univoco + 2. Oppure per elaborare e formattare contenuti e metadati da memorizzare +3. **In Combinazione con Nodo Richiesta HTTP**: + 1. Ottieni dati da interfacce esterne + 2. Dopo elaborazione, memorizza nel database vettoriale + +## ⚠️ Note Importanti +### Progettazione ID Business +**La progettazione dell'ID business influisce direttamente sull'efficienza di gestione del contenuto successivo:** +- Assicura l'unicità dell'ID business, evita sovrascritture di contenuti esistenti dovute a memorizzazione duplicata +- Utilizza modalità di denominazione ID significative e facilmente identificabili per facilitare la gestione +- Considera la modalità di denominazione prefisso + categoria + numero, come "PRD_FAQ_001" +- Se utilizzi ID casuali, assicurati di salvare la corrispondenza tra ID e contenuto + +### Formato e Qualità del Contenuto +**La qualità del contenuto memorizzato influisce direttamente sull'effetto di ricerca successivo:** +- Evita di memorizzare troppe informazioni irrilevanti, concentrati sul contenuto core +- Assicura formati di testo uniformi, rimuovi tag HTML e altri simboli di formattazione +- Per contenuti non testuali come tabelle e grafici, converti in descrizioni testuali prima di memorizzare +- Aggiorna e mantieni regolarmente il contenuto della knowledge base per mantenere accuratezza e tempestività delle informazioni + +### Sicurezza e Permessi +**La sicurezza dei dati della knowledge base richiede particolare attenzione:** +- Evita di memorizzare informazioni personali sensibili o segreti aziendali +- Imposta marcatori di permessi di accesso attraverso metadati +- Verifica regolarmente il contenuto della knowledge base per garantire conformità + +## ❓ Problemi Comuni +### Problema 1: Dopo la memorizzazione del contenuto non riesco a trovarlo tramite ricerca vettoriale, come fare? +**Soluzioni**: +- Verifica se l'ID del database vettoriale corrisponde, assicurati che ricerca e memorizzazione utilizzino lo stesso database vettoriale +- Conferma la qualità del contenuto memorizzato, contenuti troppo brevi o privi di significato potrebbero essere difficili da ricercare +- Regola la soglia di similarità del nodo Ricerca Vettoriale, abbassala adeguatamente per ottenere più risultati +- Verifica se il testo di query di ricerca sia semanticamente correlato al contenuto memorizzato + +### Problema 2: Come aggiornare contenuti già memorizzati? +**Soluzioni**: +- Utilizza lo stesso ID business per memorizzare nuovamente il contenuto, sovrascriverà il contenuto originale +- Se necessiti di eliminare completamente e poi creare, puoi prima utilizzare il nodo Cancellazione Vettoriale per eliminare, poi memorizzare nuovo contenuto +- Per aggiornamenti parziali, si consiglia di utilizzare nuovo contenuto completo per sovrascrivere quello vecchio, invece di aggiornare solo una parte + +### Problema 3: La memorizzazione di grandi quantità di contenuti è lenta, come gestire? +**Soluzioni**: +- Elabora grandi quantità di contenuti in batch, evita di memorizzare troppi dati in una sola volta +- Utilizza il nodo ciclo per memorizzare contenuti in batch +- Ottimizza la dimensione del contenuto, memorizza solo informazioni necessarie +- Pre-elabora adeguatamente il contenuto per ridurre il carico computazionale durante la memorizzazione + +## 🏆 Migliori Pratiche +### Nodi Comuni da Abbinare +|Tipo Nodo|Motivo Abbinamento| +|---|---| +|Nodo Segmentazione Testo|Segmenta testi lunghi in frammenti adatti alla memorizzazione| +|Nodo Esecuzione Codice|Elabora contenuti, genera ID business o metadati| +|Nodo Ricerca Vettoriale|Ricerca contenuti vettoriali già memorizzati| +|Nodo Cancellazione Vettoriale|Elimina contenuti vettoriali non più necessari| +|Nodo Ciclo|Elabora e memorizza in batch numerosi contenuti| + +--- + # 向量存储节点 ## 什么是向量存储节点？ 向量存储节点是Magic Flow工作流中用于将文本内容存储到向量数据库的功能组件。它能够将文本内容转换为向量形式并保存在知识库中，便于后续的语义检索和内容匹配。简单来说，向量存储就像是一个智能信息仓库，不仅存储了内容本身，还保留了内容的语义特征，使得后续可以通过语义相似度进行查询。 diff --git a/docs/zh/tutorial/basic/node/end-node.md b/docs/zh/tutorial/basic/node/end-node.md index 7f627335b..447d9b7b0 100644 --- a/docs/zh/tutorial/basic/node/end-node.md +++ b/docs/zh/tutorial/basic/node/end-node.md @@ -1,4 +1,109 @@ -# 结束节点 +# Nodo di Fine 🔚 + +## Che cos'è il nodo di fine? +Il nodo di fine è l'ultimo nodo di un flusso di lavoro; serve a restituire le informazioni di risultato al termine dell'esecuzione. Ogni flusso di lavoro necessita almeno di un nodo di fine, ma è possibile averne più di uno per gestire diversi percorsi di terminazione. + +Immagine esplicativa: + +L'interfaccia del nodo di fine contiene l'area di configurazione "Output", dove puoi definire i parametri da restituire alla fine del flusso. È possibile aggiungere più parametri di output; per ciascuno si impostano nome parametro, nome visualizzato e valore. Il valore può essere un'espressione o un valore fisso e può referenziare dati prodotti da altri nodi del flusso. +![结束节点](https://cdn.letsmagic.cn/static/img/End-node.png) + +## Perché serve il nodo di fine? +Nel disegno dei flussi, il nodo di fine risolve questi punti chiave: +1. Chiarezza del punto di termine: marca esplicitamente dove termina l'esecuzione, rendendo più chiara la logica del flusso. +2. Definizione dell'output: consente di configurare cosa esporre come risultato finale. +3. Ritorno dati coerente: formatta e organizza l'output per garantirne coerenza e usabilità. +4. Supporto a flussi complessi: su percorsi multipli, nodi di fine diversi possono restituire risultati differenti. + +## Scenari tipici +### 1. Flusso Q&A intelligente +Restituisce la risposta finale elaborata e, se necessario, raccomandazioni o riferimenti. +### 2. Flussi di elaborazione dati +Ritorna risultati elaborati come report statistici o conclusioni di analisi. +### 3. Sottoprocessi +Quando il flusso è invocato come sottoprocesso, definisce i dati da restituire al flusso principale, come il valore di ritorno di una funzione. + +## Parametri del nodo +### Parametri di output +La configurazione centrale è l'output, ovvero i dati da restituire alla fine: +|Voce|Descrizione|Obbligatorio| +|---|---|---| +|Nome|Identificatore del parametro per i riferimenti nel sistema|Sì| +|Nome visualizzato|Nome amichevole per l'interfaccia|Sì| +|Tipo|Stringa, array, ecc.|Sì| +|Valore|Valore effettivo (fisso, espressione o variabile)|Sì| + +## Istruzioni d'uso +### Passi base +1. Aggiungi il nodo di fine: + 1. Trascinalo dal pannello nel canvas + 2. Collega l'output del nodo precedente al nodo di fine +2. Configura gli output: + 1. Clicca "Aggiungi parametro" per ogni output necessario + 2. Imposta nome (es. "result") e nome visualizzato (es. "Risultato") + 3. Scegli tipo di valore (espressione o fisso) + 4. Con espressioni, usa `${nomeVariabile}` per referenziare variabili del flusso +3. Salva: + 1. Verifica di aver configurato tutti gli output necessari + 2. Salva la configurazione del nodo + +### Suggerimenti avanzati +#### Organizzazione multi-parametro +Per restituire parametri correlati: +1. Raggruppa per funzione o tipo di dato +2. Usa strutture annidate JSON, ad es. `{"data": ${result}, "meta": ${metadata}}` +3. Segui regole di naming coerenti, es. `result_main`, `result_details` + +#### Output dinamici +Restituisci risultati diversi su percorsi diversi: +1. Preponi una diramazione condizionale e collega a nodi di fine diversi +2. Pre-impacchetta i possibili risultati in un'unica variabile tramite un nodo codice e referenzialo qui + +## Note +### Naming dei parametri +1. Evita caratteri speciali; usa lettere, numeri e underscore +2. Naming semantico, es. `search_result` invece di `data` +3. Mantieni coerenza tra più nodi di fine nello stesso flusso + +### Tipi di dato +1. Garantisci la compatibilità con ciò che il consumer si aspetta +2. Converti formati con un nodo codice quando serve +3. Gestisci i null con default ragionevoli + +### Gestione di più nodi di fine +1. Etichettali chiaramente +2. Pianifica i percorsi assicurando un nodo di fine per ciascuno +3. Mantieni coerente la struttura dei parametri chiave + +## FAQ +### Perché i parametri di output non compaiono nel risultato? +1. Controlla il nome (typo) +2. Verifica la sintassi dell'espressione e l'esistenza della variabile +3. Verifica che l'esecuzione arrivi al nodo di fine +4. Verifica lo scope delle variabili + +### Come restituire strutture complesse? +1. Usa JSON: `{"items": ${list}, "count": ${count}}` +2. Prepara i dati prima con un nodo codice +3. Usa naming gerarchico: `result_header`, `result_body`, `result_footer` + +### Come garantire un termine corretto su percorsi multipli? +1. Analizza i percorsi possibili +2. Prevedi un nodo di fine per ogni percorso principale +3. Uniforma la struttura del payload +4. Includi uno stato (`status`, `code`) per distinguere i casi + +## Nodi spesso abbinati +|Tipo nodo|Motivo| +|---|---| +|Diramazione condizionale|Collega a nodi di fine diversi per risultati diversi| +|Esecuzione codice|Prepara e formatta l'output finale| +|Chiamata modello LLM|Genera risposte strutturate poi restituite| +|Risposta messaggio|Invia un messaggio prima della fine e registra l'esito| + +--- + +# 中文原文 ## 什么是结束节点？ 结束节点是工作流的最终节点，用于返回工作流程运行后的结果信息。每个工作流至少需要一个结束节点，但也可以有多个结束节点对应不同的结束路径。 @@ -99,4 +204,4 @@ |条件分支节点|根据不同条件连接到不同的结束节点，返回不同结果| |代码执行节点|在结束前整理和格式化最终输出数据| |大模型调用节点|生成结构化的回答内容，然后由结束节点返回| -|消息回复节点|在结束前向用户发送消息，结束节点则记录操作结果| \ No newline at end of file +|消息回复节点|在结束前向用户发送消息，结束节点则记录操作结果| diff --git a/docs/zh/tutorial/basic/open-api/flow-open-api.md b/docs/zh/tutorial/basic/open-api/flow-open-api.md index 7a797b697..b0c067735 100644 --- a/docs/zh/tutorial/basic/open-api/flow-open-api.md +++ b/docs/zh/tutorial/basic/open-api/flow-open-api.md @@ -1,3 +1,176 @@ +# 📘 Documentazione API di Magic Flow + +## 🔐 1. Autenticazione +Le API supportano due metodi di autenticazione. Puoi fornire la tua API Key in uno dei due modi seguenti: + +Metodo 1: Intestazione api-key (consigliato) +``` +api-key: YOUR_API_KEY +``` + +Metodo 2: Intestazione Authorization +``` +Authorization: Bearer YOUR_API_KEY +``` + +Formato della chiave: inizia con `api-sk-`. +Per istruzioni sulla generazione e configurazione dell’API Key, vedi: https://www.teamshare.cn/knowledge/preview/710857519214628864/775765654906695680 + +## 📎 2. Spiegazioni di base +- URL base delle API: `https://[API_HOST]` +- Tutte le richieste e risposte usano JSON +- I timestamp usano il formato ISO 8601 +- Tutte le richieste devono includere le intestazioni di autenticazione + +## 🧩 3. Elenco delle API + +### 3.1 Chat API +Crea una conversazione, supporta dialoghi generali e in modalità Flow. +- Percorso: `/api/chat` +- Metodo: `POST` +- Content-Type: `application/json` + +Parametri richiesta: +| Nome | Tipo | Obbligatorio | Descrizione | +|---|---|---|---| +| message | string | Sì | Contenuto del messaggio | +| conversation_id | string | No | ID conversazione per mantenere il contesto; se omesso, il server ne crea uno nuovo e lo restituisce | +| attachments | array | No | Elenco degli allegati (solo l’API chat lo supporta) | +| stream | boolean | No | Abilita risposta in streaming, predefinito false | + +Allegati: carica prima i file su un URL pubblico, quindi fornisci i riferimenti nella richiesta. +Esempio struttura allegato: +```json +{ + "attachment_name": "filename.ext", + "attachment_url": "https://example.com/path/to/file" +} +``` + +Tipi di allegato supportati: +- Immagini: jpeg, jpg, png, gif +- Documenti: pdf, doc, docx, txt + +Note sugli allegati: +1) L’URL deve essere pubblicamente accessibile +2) Dimensione massima 10MB +3) Per analisi immagini serve un modello che supporti la visione + +Struttura risposta (principale): +| Campo | Tipo | Descrizione | +|---|---|---| +| conversation_id | string | ID conversazione | +| messages | array | Array di messaggi (stessa struttura del non-stream) | + +Struttura oggetto messaggio: +| Campo | Tipo | Descrizione | +|---|---|---| +| id | string | ID messaggio | +| message | object | Contenuto del messaggio | +| conversation_id | string | ID conversazione | +| error_information | string | Dettagli errore, se presenti | +| success | boolean | Indica successo esecuzione, default true | + +Esempi richiesta/risposta e streaming: invariati nei blocchi di codice sottostanti. + +### 3.2 API chiamata con parametri +Esegue chiamate con parametri. +- Percorso: `/api/param-call` +- Metodo: `POST` +- Content-Type: `application/json` + +Parametri richiesta: +| Nome | Tipo | Obbligatorio | Descrizione | +|---|---|---|---| +| message | string | Sì | Contenuto del messaggio | +| conversation_id | string | No | ID conversazione (solo a fini di log) | +| params | object | Sì | Parametri chiave-valore della chiamata | + +Parametri risposta: +| Campo | Tipo | Descrizione | +|---|---|---| +| conversation_id | string | ID conversazione | +| result | object | Risultato dell’esecuzione | + +Gli esempi di richiesta e risposta sono riportati nei blocchi sottostanti. + +### 3.3 Chat asincrona +Crea una conversazione in modalità asincrona. +- Percorso: `/api/async-chat` +- Metodo: `POST` +- Content-Type: `application/json` + +Parametri richiesta: +| Nome | Tipo | Obbligatorio | Descrizione | +|---|---|---|---| +| message | string | Sì | Contenuto del messaggio | +| conversation_id | string | No | ID conversazione | +| attachments | array | No | Elenco allegati, stesso formato della Chat API | +| async | boolean | Sì | Deve essere true | + +Parametri risposta: +| Campo | Tipo | Descrizione | +|---|---|---| +| conversation_id | string | ID conversazione | +| task_id | string | ID del task asincrono | + +Gli esempi di richiesta e risposta sono riportati nei blocchi sottostanti. + +### 3.4 Chiamata con parametri (asincrona) +- Percorso: `/api/param-call` +- Metodo: `POST` +- Content-Type: `application/json` + +Parametri richiesta: +| Nome | Tipo | Obbligatorio | Descrizione | +|---|---|---|---| +| message | string | Sì | Contenuto del messaggio | +| conversation_id | string | No | ID conversazione (solo log) | +| params | object | Sì | Parametri chiave-valore | +| async | boolean | Sì | Deve essere true | + +Parametri risposta: +| Campo | Tipo | Descrizione | +|---|---|---| +| conversation_id | string | ID conversazione | +| task_id | string | ID del task asincrono | + +### 3.5 Recupero risultato asincrono +Ottieni il risultato dell’elaborazione di un task asincrono. +- Percorso: `/api/async-chat/{task_id}` +- Metodo: `GET` + +Parametri richiesta: +| Nome | Tipo | Obbligatorio | Descrizione | +|---|---|---|---| +| task_id | string | Sì | ID del task asincrono (nel path) | + +Parametri risposta: +| Campo | Tipo | Descrizione | +|---|---|---| +| task_id | string | ID task | +| status | integer | Codice stato | +| status_label | string | Descrizione stato: "pending" | "processing" | "completed" | "failed" | +| created_at | string | Data creazione | +| result | object | Risultato (solo quando completato) | + +Gli esempi per chat e chiamate parametriche sono riportati nei blocchi sottostanti. + +## 🧯 4. Codici di errore +| Codice | Descrizione | +|---|---| +| 400 | Parametri richiesta non validi | +| 401 | Non autorizzato, API Key non valida | +| 403 | Permessi insufficienti | +| 404 | Risorsa non trovata | +| 429 | Troppe richieste | +| 500 | Errore interno del server | + +Esempio di risposta errore: invariato nel blocco sottostante. + +--- + +# 中文原文 # Magic Flow API 接口文档 ## 一、认证方式 API 支持两种认证方式，您可以选择以下任一方式提供 API Key： diff --git a/docs/zh/tutorial/basic/reply-node.md b/docs/zh/tutorial/basic/reply-node.md index cb916c7c8..be9e7bf81 100644 --- a/docs/zh/tutorial/basic/reply-node.md +++ b/docs/zh/tutorial/basic/reply-node.md @@ -1,3 +1,114 @@ +# 💬 Nodo Risposta + +Il nodo risposta è utilizzato per inviare risposte a utenti o sistemi esterni. È solitamente utilizzato alla fine del flusso o prima del nodo finale. + +## 📋 Panoramica + +Il nodo risposta gestisce l'output del flusso, formattando e inviando i dati al destinatario in formato appropriato. + +## ⚙️ Configurazione + +### Impostazioni Base + +- **Nome**: Identificatore univoco del nodo +- **Descrizione**: Descrizione opzionale dello scopo del nodo +- **Tipo**: Impostato su "risposta" (sola lettura) + +### Impostazioni Risposta + +1. **Formato Risposta** + - JSON + - XML + - Testo semplice + - HTML + - Formato personalizzato + +2. **Intestazioni Risposta** + - Content-Type + - Codice stato + - Intestazioni personalizzate + +3. **Corpo Risposta** + - Contenuto statico + - Contenuto dinamico (utilizzando espressioni) + - Contenuto basato su template + +## 💡 Esempi di Utilizzo + +### Risposta JSON + +```javascript +// Esempio configurazione nodo risposta per risposta JSON +{ + "type": "reply", + "config": { + "format": "json", + "statusCode": 200, + "headers": { + "Content-Type": "application/json" + }, + "body": { + "status": "success", + "data": "${context.processedData}" + } + } +} +``` + +### Risposta HTML + +```javascript +// Esempio configurazione nodo risposta per risposta HTML +{ + "type": "reply", + "config": { + "format": "html", + "statusCode": 200, + "headers": { + "Content-Type": "text/html" + }, + "body": "

${context.title}

${context.message}

" + } +} +``` + +## 🌟 Migliori Pratiche + +1. **Formattazione Risposta** + - Utilizzare tipo contenuto appropriato + - Mantenere consistenza formato dati + - Includere dettagli errore quando necessario + +2. **Gestione Errori** + - Impostare codice stato appropriato + - Includere messaggio errore + - Registrare dettagli errore + +3. **Performance** + - Minimizzare dimensione risposta + - Utilizzare compressione quando appropriato + - Memorizzare risposta quando possibile + +## ❓ Problemi Comuni + +1. **Errori Formato** + - Controllare sintassi JSON/XML + - Verificare espressioni template + - Confermare intestazione tipo contenuto + +2. **Ritardo Risposta** + - Ottimizzare elaborazione dati + - Controllare ritardo rete + - Monitorare tempo risposta + +## 🔗 Nodi Correlati + +- [Nodo Iniziale](./start-node.md) +- [Nodo Attesa](./wait-node.md) +- [Nodo Finale](./end-node.md) + +--- + # 回复节点 回复节点用于向用户或外部系统发送响应。它通常用于流程的末尾或在结束节点之前。 diff --git a/docs/zh/tutorial/basic/start-node.md b/docs/zh/tutorial/basic/start-node.md index e3df46027..3a94581cd 100644 --- a/docs/zh/tutorial/basic/start-node.md +++ b/docs/zh/tutorial/basic/start-node.md @@ -1,3 +1,106 @@ +# 🚀 Nodo Iniziale + +Il nodo iniziale è il punto di ingresso di qualsiasi flusso in Magic. Definisce come inizia il flusso e quali dati iniziali riceve. + +## 📋 Panoramica + +Il nodo iniziale è il primo nodo nel flusso, non può essere connesso da nessun altro nodo lato input. Può avere solo connessioni output. + +## ⚙️ Configurazione + +### Impostazioni Base + +- **Nome**: Identificatore univoco del nodo +- **Descrizione**: Descrizione opzionale dello scopo del nodo +- **Tipo**: Impostato su "iniziale" (sola lettura) + +### Parametri Input + +Il nodo iniziale può essere configurato per accettare vari tipi di input: + +1. **Richiesta HTTP** + - Metodo (GET, POST, PUT, DELETE) + - Intestazioni richiesta + - Parametri query + - Corpo richiesta + +2. **Webhook** + - URL + - Autenticazione + - Formato payload + +3. **Attività Programmata** + - Espressione Cron + - Fuso orario + - Opzioni ripetizione + +## 💡 Esempi di Utilizzo + +### Endpoint HTTP + +```javascript +// Esempio configurazione nodo iniziale per endpoint HTTP +{ + "type": "start", + "config": { + "method": "POST", + "path": "/api/process", + "headers": { + "Content-Type": "application/json" + } + } +} +``` + +### Attività Programmata + +```javascript +// Esempio configurazione nodo iniziale per attività programmata +{ + "type": "start", + "config": { + "schedule": "0 0 * * *", // Esegue ogni giorno a mezzanotte + "timezone": "UTC" + } +} +``` + +## 🌟 Migliori Pratiche + +1. **Norme Denominazione** + - Utilizzare nomi descrittivi che indicano lo scopo + - Includere tipo trigger nel nome (esempio: "HTTP_Inizio", "Programmata_Inizio") + +2. **Gestione Errori** + - Validare sempre dati input + - Includere risposte errore appropriate + - Registrare eventi importanti + +3. **Sicurezza** + - Implementare autenticazione appropriata + - Validare dati input + - Utilizzare HTTPS per endpoint HTTP + +## ❓ Problemi Comuni + +1. **Configurazione Non Valida** + - Controllare metodo e percorso endpoint HTTP + - Validare espressione cron attività programmate + - Assicurare che tutti campi obbligatori siano compilati + +2. **Problemi Connessione** + - Verificare connessione rete + - Controllare impostazioni firewall + - Validare certificati SSL + +## 🔗 Nodi Correlati + +- [Nodo Risposta](./reply-node.md) +- [Nodo Attesa](./wait-node.md) +- [Nodo Finale](./end-node.md) + +--- + # 开始节点 开始节点是 Magic 中任何流程的入口点。它定义了流程如何开始以及接收什么初始数据。 diff --git a/docs/zh/tutorial/basic/wait-node.md b/docs/zh/tutorial/basic/wait-node.md index 6029dd08f..16842be83 100644 --- a/docs/zh/tutorial/basic/wait-node.md +++ b/docs/zh/tutorial/basic/wait-node.md @@ -1,3 +1,105 @@ +# ⏳ Nodo Attesa + +Il nodo attesa è utilizzato per sospendere l'esecuzione del flusso fino al termine della durata specificata o al soddisfacimento di condizioni particolari. + +## 📋 Panoramica + +Il nodo attesa permette di controllare il tempo di esecuzione del flusso, utile per limitazione velocità, polling o coordinamento con sistemi esterni. + +## ⚙️ Configurazione + +### Impostazioni Base + +- **Nome**: Identificatore univoco del nodo +- **Descrizione**: Descrizione opzionale dello scopo del nodo +- **Tipo**: Impostato su "attesa" (sola lettura) + +### Impostazioni Attesa + +1. **Tipo Attesa** + - Durata fissa + - Fino al soddisfacimento condizione + - Fino all'ora specificata + - Fino all'occorrenza evento + +2. **Impostazioni Durata** + - Valore tempo + - Unità tempo (secondi, minuti, ore) + - Intervallo casuale (opzionale) + +3. **Impostazioni Condizione** + - Espressione + - Tempo timeout + - Opzioni retry + +## 💡 Esempi di Utilizzo + +### Attesa Durata Fissa + +```javascript +// Esempio configurazione nodo attesa per durata fissa +{ + "type": "wait", + "config": { + "waitType": "duration", + "duration": 30, + "unit": "seconds" + } +} +``` + +### Attesa Condizione + +```javascript +// Esempio configurazione nodo attesa per condizione +{ + "type": "wait", + "config": { + "waitType": "condition", + "condition": "${context.data.status} === 'ready'", + "timeout": 300, + "retryInterval": 10 + } +} +``` + +## 🌟 Migliori Pratiche + +1. **Gestione Timeout** + - Impostare tempo timeout appropriato + - Gestire scenari timeout + - Registrare eventi timeout + +2. **Gestione Risorse** + - Evitare tempi attesa troppo lunghi + - Utilizzare intervalli appropriati + - Monitorare risorse sistema + +3. **Gestione Errori** + - Gestire errori valutazione condizione + - Registrare eventi attesa + - Fornire comportamento di fallback + +## ❓ Problemi Comuni + +1. **Problemi Timeout** + - Controllare sintassi condizione + - Validare valori timeout + - Monitorare carico sistema + +2. **Esaurimento Risorse** + - Limitare attese concorrenti + - Utilizzare intervalli appropriati + - Monitorare risorse sistema + +## 🔗 Nodi Correlati + +- [Nodo Iniziale](./start-node.md) +- [Nodo Risposta](./reply-node.md) +- [Nodo Finale](./end-node.md) + +--- + # 等待节点 等待节点用于暂停流程的执行，直到指定的持续时间结束或满足特定条件。 diff --git a/docs/zh/tutorial/best-practice/build-a-store-knowledge-assistant.md b/docs/zh/tutorial/best-practice/build-a-store-knowledge-assistant.md index 3309511df..ec23163ea 100644 --- a/docs/zh/tutorial/best-practice/build-a-store-knowledge-assistant.md +++ b/docs/zh/tutorial/best-practice/build-a-store-knowledge-assistant.md @@ -1,3 +1,113 @@ +# 🏬 Costruire un Assistente di Conoscenza per il Negozio + +Questo tutorial usa come esempio la costruzione di un “Assistente di Conoscenza del Negozio”, spiegando come utilizzare la funzione di knowledge base di Magic per realizzare scenari di Q&A basati sulla conoscenza. + +## 🧠 Conoscenze di Sfondo +Magic è una nuova generazione di piattaforma di authoring per AI Chat Bot. Che tu abbia o meno basi di programmazione, puoi creare rapidamente vari tipi di Chat Bot e pubblicarli per l’uso nel team. +Teamshare Knowledge Base è una piattaforma di gestione informativa interna all’azienda, che supporta gestione documenti, creazione Wiki e Q&A interattivo, includendo controllo versioni, impostazione permessi e ricerca ottimizzata, migliorando la collaborazione e la condivisione della conoscenza. + +## 📌 Introduzione al Caso +Con l’aumento del numero di negozi, crescono anche le richieste dei commessi verso il reparto centrale. Per migliorare l’efficienza e servire meglio i negozi, basandoci su Magic costruiamo un “Assistente di Conoscenza del Negozio”. Può rispondere rapidamente e con precisione a domande comuni come “gestione dispositivi e risoluzione guasti” o “operazione sistema cassa”, migliorando sensibilmente l’efficienza operativa del centro. + +## 🧭 Progettazione del Flusso +(Da integrare) + +## 🏗️ Passi di Costruzione +### Passo 1: Raccolta Dati +- Confermare le fonti informative: analizza i ticket storici dei negozi e categorizza i problemi. + +Esempi di categorie e contenuti: +> “La fattura può sostituire il buono?” — Categoria finanziaria +> “Guasto stampante A4 / stampante termica?” — Categoria post‑vendita ingegneria materiali + +Secondo passo: raccolta e organizzazione dei contenuti +| Categoria | Contenuto | Fonte | +|---|---|---| +| Finanza | Regole di rimborso | “Regolamento rimborso finanziario” | +| Q&A rimborso (integrazioni) | Nuovo documento cloud | +| HR & Amministrazione | Timbratura e turni | Knowledge base HR | +| Sistemi interni | Cassa | Nuovo documento cloud | +| Guasti di rete | Interruzioni ecc. | Nuovo documento cloud | +| Manuali stampanti | Manuali d’uso | — | +| Turni | Ricerca personale di turno | Nuovo documento cloud; mantenimento info turni | + +Nota: la classificazione reale sarà più ricca; qui è solo di riferimento per la metodologia. + +### Passo 2: Creare la Knowledge Base +- Per basi esistenti (es. regolamenti), importa direttamente le basi già mantenute da altri team. +- Per Q&A su guasti e problemi comuni, crea una nuova knowledge base e aggiungi/manutieni i contenuti: +1) Accedi a Magic +2) Crea la knowledge base “Knowledge Base del Negozio”, organizza per cartelle +3) Inserisci i contenuti in formato “domanda-risposta” per migliorare il hit rate di ricerca +Al termine del riempimento, la base è pronta. +Guida operativa dettagliata: “Configurare Q&A su Knowledge” https://www.teamshare.cn/knowledge/preview/710857519214628864/754479332682764288 + +### Passo 3: Costruire l’AI Assistant +1) Accedi a Magic: https://www.letsmagic.cn/explore +2) Crea un AI Assistant (nome: Assistente Conoscenza Negozio; descrizione: rispondo alle questioni relative ai negozi) +3) Orchestrazione del flusso del bot. Flusso generale: +![FigxmKkXEa2k3XAdDoUgHxf77g2Z.png](https://cdn.letsmagic.cn/static/img/20250512162935.jpg) + +Configurazioni chiave: +| Nome Nodo | Configurazione | +|---|---| +| Nodo Iniziale | Usa 4 eventi; “quando aggiunge come amico” → nodo risposta con saluto e guida. “Quando riceve nuovo messaggio” → collega nodo esecuzione codice e nodo strumenti | +| Nodo Esecuzione Codice | Determina se l’utente è “internazionale” in base a conversationId. Input: conversationId (stringa, valore fisso dal nodo iniziale). Output: isNationalUser. Codice PHP utilizzato (non modificare): return [ 'isNationalUser' => str_contains($conversationId, 'TBC-D-xxxxx') ? '是' : '否', ]; | +| Nodo Strumento | Recupera contenuti da “documento cloud”: tool teamshare_doc_markdown_query; parametrizza l’ID del documento; quindi collega il nodo “Chiamata Modello Grande” | +| Nodo Chiamata Modello Grande | Modello: GPT‑4o; Strumenti: user_search, create_group; Knowledge base: aggiungi “Knowledge Base del Negozio” e “Knowledge base HR”; Prompt: lasciato vuoto in questa fase. L’output va mostrato in un nodo risposta testo | +| Nodo Log (opzionale) | Dopo la risposta LLM, registra domanda e risposta per audit/soddisfazione: tool log_question_and_answer; input: answer (risposta LLM), is_national_user | + +### Passo 4: Scrivere i Prompt +I prompt includono: impostazione ruolo, contesto, descrizione capacità e vincoli. + +Ruolo (esempio sintetico): +“Sei l’Assistente di Conoscenza del Negozio. Stile cordiale, professionale e conciso; rispondi nella lingua dell’utente; se l’utente scrive in inglese, effettua retrieval in cinese e poi rispondi in inglese; preferisci contenuti con immagini quando disponibili.” + +Contesto: include cronologia chat, knowledge esterne, profilo utente (reparto/ruolo/turno). Usa le variabili dei nodi precedenti tramite @. + +Capacità: elenca capacità come “gestione dispositivi e troubleshooting”, “operazioni sistema cassa”, “post‑vendita e gestione materiali”, “linee guida processi/regolamenti”, ecc., e specifica che le risposte devono basarsi sui risultati di retrieval. + +Vincoli (esempio): +1) Quando chiami teamshare_knowledge_search, setta knowledge_list in base a isNationalUser. +2) A parte “chi sei/cosa sai fare”, tutte le risposte devono basarsi su retrieval; evita allucinazioni. +3) Risposte strutturate e concise; niente contenuti fuori tema. +4) Se l’utente ripete la stessa domanda, riesegui il retrieval (non basarti solo sul contesto). +5) Adatta le risposte al reparto/ruolo dell’utente quando possibile. + +Prompt completo: resta invariato nel documento originale per tutela struttura; mantieni stile conciso e ben formattato. + +### Passo 5: Debug e Pubblicazione +1) Clic “Prova esecuzione” per valutare l’effetto dell’assistente +![Fi37wHLpYs9I6JomVXW4ZT6_l1oH.png](https://cdn.letsmagic.cn/static/img/Fi37wHLpYs9I6JomVXW4ZT6_l1oH.png) + +2) Verifica se l’output della risposta è conforme alle attese +![FhDUPfdOisZ3eUrWDhEus6Gjvyto.png](https://cdn.letsmagic.cn/static/img/FhDUPfdOisZ3eUrWDhEus6Gjvyto.png) + +3) Se tutto ok, clicca “Pubblica” per farlo provare agli altri +![FowHlZdD4BUfNUmgcjd-N60NU2hG.png](https://cdn.letsmagic.cn/static/img/FowHlZdD4BUfNUmgcjd-N60NU2hG.png) + +### Passo 6: Pubblicare su Piattaforme Terze (Opzionale) +Ad esempio DingTalk: +1) In Magic, nel pannello di pubblicazione, clic “Aggiungi piattaforma” +2) Imposta un identificatore bot leggibile (es. dingtalk_store_assistant) +3) Su DingTalk Open Platform, crea app e copia client id/secret +4) Torna su Magic e incolla id/secret per completare binding +5) Ottieni l’URL di ricezione messaggi e configurarlo su DingTalk +6) Pubblica su DingTalk e verifica messaggistica +7) Infine, spunta la piattaforma appena aggiunta e pubblica il bot + +## ✅ Effetto Finale +Effetto in Magic: +![20250512171912.jpg](https://cdn.letsmagic.cn/static/img/20250512171912.jpg) + +Effetto in DingTalk: +![20250512172022.jpg](https://cdn.letsmagic.cn/static/img/20250512172022.jpg) + +A questo punto, l’Assistente di Conoscenza del Negozio è stato completato. + +--- + +# 中文原文 本教程以搭建一个门店知识助理为例，说明如何使用麦吉的知识库功能来实现知识问答场景。 ## 背景知识 **Magic麦吉** 新一代 AI Chat Bot 的应用编辑平台，无论你是否有编程基础，都可以通过这个平台快速创建各种类型的Chat Bot，发布到团队上使用。 diff --git a/docs/zh/tutorial/best-practice/complex-tasks-in-one-sentence.md b/docs/zh/tutorial/best-practice/complex-tasks-in-one-sentence.md index 1487a72f3..3a9a83553 100644 --- a/docs/zh/tutorial/best-practice/complex-tasks-in-one-sentence.md +++ b/docs/zh/tutorial/best-practice/complex-tasks-in-one-sentence.md @@ -1,3 +1,51 @@ +# 🚀 Realizzare Compiti Complessi con una Frase + +## 📚 Conoscenze di Base +Nel lavoro, solitamente abbiamo bisogno di comprendere l'intenzione del superiore attraverso una frase, e scomporla in compiti lavorativi, eseguendola passo dopo passo. Questo documento mostra come, in Magic, realizzare la gestione di compiti complessi attraverso una frase. + +## 📋 Introduzione al Caso +L'Assistente Progetto Magic è utilizzato nella gestione aziendale per assistere i manager nel completare la gestione progetti, aiutando i manager a gestire le questioni frammentarie del follow-up progetti, permettendo ai manager di progetti di concentrare il tempo sugli affari core. + +## 🛠️ Modalità di Realizzazione: +**Agente di Pensiero (DeepSeek)**: Output piano di esecuzione compiti. + +**Agente di Suddivisione Compiti (GPT4o)**: Responsabile della suddivisione passi compiti. + +**Agente di Esecuzione Compiti (GPT4o)**: Esegue i compiti secondo i passi + +## 📝 Passi di Realizzazione + +### I. Costruire il Processo Principale: +1. Utilizzare il modello DeepSeek-R1 per comprendere e pensare l'intenzione utente +2. Attraverso il nodo intenzione, giudicare se procedere con suddivisione compiti o esecuzione compiti +3. Descrivere gli strumenti necessari da utilizzare e le capacità degli strumenti + +![Processo Principale](https://cdn.letsmagic.cn/static/img/flow1.png) + +### II. Costruire il Processo di Suddivisione Compiti, secondo l'intenzione utente ragionata, scomporre passi e compiti +1. Creare un processo di suddivisione compiti + +![Processo Suddivisione Compiti](https://cdn.letsmagic.cn/static/img/flow2.png) + +2. Selezionare GPT4o come modello per la suddivisione compiti + +![Selezione Modello](https://cdn.letsmagic.cn/static/img/flow3.png) + +### III. Costruire il Processo di Esecuzione Compiti, caricare gli strumenti corrispondenti +1. Creare il processo per eseguire i compiti + +![Processo Esecuzione Compiti](https://cdn.letsmagic.cn/static/img/flow4.png) + +2. Caricare gli strumenti necessari per eseguire i compiti + +![Caricamento Strumenti](https://cdn.letsmagic.cn/static/img/flow5.png) + +### IV. Osservare e Verificare l'Effetto + +![Verifica Effetto](https://cdn.letsmagic.cn/static/img/flow5.png) + +--- + # 一句话实现复杂任务 ## 背景知识 在工作中，我们通常需要通过上级的一句话，去理解上级的意图，并拆解成工作任务，和一步步执行， 本文档展示在麦吉中，如何通过一句话实现复杂任务的处理 diff --git a/docs/zh/tutorial/best-practice/guide-to-using-the-magic-approval-assistant.md b/docs/zh/tutorial/best-practice/guide-to-using-the-magic-approval-assistant.md index 2fa4fef98..c8eae182b 100644 --- a/docs/zh/tutorial/best-practice/guide-to-using-the-magic-approval-assistant.md +++ b/docs/zh/tutorial/best-practice/guide-to-using-the-magic-approval-assistant.md @@ -1,3 +1,61 @@ +# 🌟 Guida all'Uso dell'Assistente di Approvazione Magic 🌟 + +## 📌 Introduzione al Prodotto +L'Assistente di Approvazione AI Magic è uno strumento intelligente per la gestione delle approvazioni, che utilizza la tecnologia AI per avviare rapidamente, revisionare intelligentemente e prendere decisioni automatiche, migliorando significativamente l'efficienza dei processi di approvazione. + +## 🚀 Punti di Forza delle Funzionalità Core +✅ Avvio con una frase: Non richiede la compilazione di moduli complessi, genera automaticamente inserendo la richiesta. +✅ Revisione intelligente AI: Verifica automaticamente la ragionevolezza dei dati, evita errori umani (promemoria rischio medio/alto/basso). +✅ Decisione automatica: L'AI apprende le abitudini dell'approvatore, supporta la delega all'AI per la gestione (approva/rifiuta/chiede chiarimenti). + +## 🎯 Guida Operativa + +### 1. Aprire l'Assistente di Approvazione Magic +Accedi a DingTalk → Clicca sulla barra di navigazione "Pannello di Lavoro" → Nella lista completa→Centro Tecnologico trova "Assistente di Approvazione Magic" (supporta ricerca rapida nella casella di ricerca) + +![20250512165849.jpg](https://cdn.letsmagic.cn/static/img/20250512165849.jpg) + +### 2. Generare il Modulo di Approvazione con una Frase +Dopo essere entrato nella finestra di dialogo, **inserisci direttamente la richiesta di approvazione**, formato suggerito: +- Richiesta permessi: "Per [motivo] richiedo [permesso/strumento XX]" + - Esempio: "Per esigenze lavorative del ruolo, richiedo il permesso di utilizzo del software Cursor, periodo di validità 3 mesi" +- Supporta regolazione manuale (clicca sui campi del modulo per modificare direttamente) + +![20250512171421.jpg](https://cdn.letsmagic.cn/static/img/20250512171421.jpg) + +Suggerimento: Più chiara è la descrizione, più preciso sarà il modulo generato dall'AI! + +### 3. Confermare e Avviare l'Approvazione + +![20250512171631.jpg](https://cdn.letsmagic.cn/static/img/20250512171631.jpg) + +Clicca [**link di reindirizzamento]** per espandere i dettagli dell'approvazione: + +![Fu5EkV5qL7kZvGoO5cUWX1GaJ-lT.png](https://cdn.letsmagic.cn/static/img/Fu5EkV5qL7kZvGoO5cUWX1GaJ-lT.png) + +### 4. Verifica Intelligente: Evitare Rischi +Attivazione regola: Dopo l'invio si avvia automaticamente la revisione AI (supporta regole personalizzate aziendali): +- ✔️ Verifica permessi: Corrispondenza ruolo, rilevamento sovrapposizioni permessi +Il feedback dei risultati ha tre livelli: +- 🟢 Basso rischio: L'approvazione non presenta rischi evidenti, può essere approvata +- 🟡 Richiede intervento umano: L'approvazione presenta rischi sospetti, necessita ulteriore conferma o revisione manuale +- 🔴 Alto rischio: L'approvazione presenta rischi gravi, deve essere rifiutata + +![FqHb3EVycdONpMYH5GY7uPMIquAk.png](https://cdn.letsmagic.cn/static/img/FqHb3EVycdONpMYH5GY7uPMIquAk.png) + +### 5. Decisione Automatica: Liberare l'Approvatore +Se l'approvatore attiva **delega alla decisione AI** → Il sistema elabora automaticamente secondo la seguente logica: dati storici, abitudini storiche, regole di approvazione e strategie preimpostate. +Tipi di risultati decisionali: +|Risultato|Condizioni di Attivazione|Scenari Tipici| +|---|---|---| +|✅ Approva|Conforme alle regole + alto tasso di approvazione storica + previsione basso rischio|Richiestе permessi standard, rimborsi spese entro budget| +|❌ Rifiuta|Viola regole (come superamento budget/conflitto permessi)|Ruolo non tecnico richiede accesso al repository codice, spese viaggio oltre limite| +|❓ Domanda di Supporto|Informazioni ambigue/necessitano materiali aggiuntivi (fiducia AI <80%)|Spese di intrattenimento senza nome cliente, manca numero contratto| + +![FgDB0f8MfADgydzEWEqJL6dpBvJL.png](https://cdn.letsmagic.cn/static/img/FgDB0f8MfADgydzEWEqJL6dpBvJL.png) + +--- + # 🌟 麦吉审批助理使用指南 🌟 ## 📌 产品简介 @@ -15,9 +73,6 @@ ![20250512165849.jpg](https://cdn.letsmagic.cn/static/img/20250512165849.jpg) - - - ### 2.一句话生成审批表单 进入对话框后，**直接输入审批需求**，格式建议： - 权限申请："因[原因]申请[XX权限/工具]" @@ -26,21 +81,15 @@ ![20250512171421.jpg](https://cdn.letsmagic.cn/static/img/20250512171421.jpg) - - 小技巧：描述越清晰，AI生成表单越精准！ ### 3.确认无误发起审批 ![20250512171631.jpg](https://cdn.letsmagic.cn/static/img/20250512171631.jpg) - - 点击 [**跳转链接]** 即可展开审批详情信息： -![Fu5EkV5qL7kZvGoO5cUWX1GaJ-lT.png](https://cdn.letsmagic.cn/static/img/Fu5EkV5qL7kZvGoO5cUWX1GaJ-lT.png) - - +![Fu5EkV5qL7kZvGoO5GY7uPMIquAk.png](https://cdn.letsmagic.cn/static/img/Fu5EkV5qL7kZvGoO5cUWX1GaJ-lT.png) ### 4.智能校验：规避风险 规则触发：提交后自动启动AI审核（支持企业自定义规则）： @@ -52,8 +101,6 @@ ![FqHb3EVycdONpMYH5GY7uPMIquAk.png](https://cdn.letsmagic.cn/static/img/FqHb3EVycdONpMYH5GY7uPMIquAk.png) - - ### 5.自动化决策：解放审批人 如若审批人开启**委托AI决策** → 系统根据以下逻辑自动处理：历史数据、历史习惯、审批规则及预设策略。 决策结果类型： @@ -63,7 +110,6 @@ |❌ 拒绝|违反规则（如超预算/权限冲突）|非技术岗申请代码库权限、超标的差旅费| |❓ 辅助提问|信息模糊/需补充材料（AI置信度＜80%）|未注明客户名的招待费、缺少合同编号| - ![FgDB0f8MfADgydzEWEqJL6dpBvJL.png](https://cdn.letsmagic.cn/static/img/FgDB0f8MfADgydzEWEqJL6dpBvJL.png) diff --git a/docs/zh/tutorial/magic-info/core-function.md b/docs/zh/tutorial/magic-info/core-function.md index 2347d34dc..f3b5e5745 100644 --- a/docs/zh/tutorial/magic-info/core-function.md +++ b/docs/zh/tutorial/magic-info/core-function.md @@ -1,3 +1,72 @@ +# Magic - Piattaforma di Sviluppo Applicazioni AI 🧙‍♂️ + +## 1. Chat in Tempo Reale 💬 + +La funzionalità di chat interna aziendale della piattaforma Magic supporta la connessione simultanea di più persone, con un'interfaccia operativa semplice e intuitiva, proprio come WeChat che usiamo quotidianamente, permettendo ai dipendenti di padroneggiarla facilmente. Che si tratti di comunicazioni private uno-a-uno o discussioni di gruppo con più partecipanti, possono essere avviate istantaneamente. + +Per quanto riguarda la gestione dei gruppi, dispone di potenti funzioni di impostazione delle autorizzazioni, gli amministratori possono assegnare flessibilmente le autorizzazioni di diversi membri, come: +- Impostare alcuni membri come amministratori, responsabili della gestione e manutenzione quotidiana del gruppo +- Limitare le autorizzazioni di parola di alcuni membri, garantendo lo svolgimento ordinato delle discussioni di gruppo + +Attraverso tali funzionalità di messaggistica istantanea, la comunicazione interna aziendale diventa più rapida ed efficiente, le informazioni possono essere trasmesse tempestivamente, migliorando significativamente l'efficienza lavorativa. + +![Interfaccia Chat in Tempo Reale](https://cdn.letsmagic.cn/static/img/20250512164817.jpg) + +## 2. Costruzione e Gestione Assistente AI 🤖 + +- **Interno Aziendale**: Elenco degli assistenti AI consentiti per la pubblicazione interna aziendale +- **Gestione Assistente**: Controllo di versione pubblicazione, stato abilitazione, ecc. + +![Interfaccia Gestione Assistente AI](https://cdn.letsmagic.cn/static/img/20250512164212.jpg) + +![Elenco Assistenti AI](https://cdn.letsmagic.cn/static/img/ai-assistant-2.png) + +## 3. Orchestrazione Workflow 🔄 + +- **Orchestrazione Processi**: Costruzione rapida di workflow attraverso drag-and-drop, gestione di flussi di task con logica complessa e requisiti di alta stabilità. +- **Combinazione Nodi**: Fornitura di numerosi nodi flessibili e combinabili, inclusi modelli di linguaggio di grandi dimensioni, codice personalizzato, logica di giudizio, ecc. +- **Supporto Template**: La piattaforma fornisce template di workflow, riducendo la soglia di utilizzo. + +![Interfaccia Orchestrazione Workflow](https://cdn.letsmagic.cn/static/img/workflow-1.png) + +### Processi + +![Interfaccia Processi](https://cdn.letsmagic.cn/static/img/workflow-process.png) + +### Set di Strumenti + +![Interfaccia Set di Strumenti](https://cdn.letsmagic.cn/static/img/tools.png) + +## 4. Funzionalità Memoria 🧠 + +- **Memoria a Lungo Termine**: Fornitura di funzionalità di memoria come variabili, database, file, ecc., dotando i Bot di capacità di memoria a lungo termine. +- **Memoria Database**: Capacità di memoria database conveniente per l'interazione AI, può ricordare persistentemente i parametri importanti o i contenuti delle conversazioni degli utenti. + +![Interfaccia Funzionalità Memoria](https://cdn.letsmagic.cn/static/img/memory-1.png) + +![Interfaccia Memoria Database](https://cdn.letsmagic.cn/static/img/memory-2.png) + +## 5. Interazione Multimodale 🎭 + +- **Modalità di Interazione Multiple**: Supporto per molteplici modalità di interazione come testo, voce, immagini, fornendo un'esperienza utente più ricca. +- **Creazione Creativa**: Gli utenti possono utilizzare funzioni come generazione immagini AI, ritratti AI per creazioni creative. + +![Interfaccia Interazione Multimodale](https://cdn.letsmagic.cn/static/img/multimodal.png) + +## 6. Pubblicazione Applicazioni 🚀 + +- **Pubblicazione Multi-Piattaforma**: Supporto per la pubblicazione di applicazioni AI sviluppate su molteplici piattaforme come WeChat aziendale, DingTalk, ecc. + +![Interfaccia Pubblicazione Applicazioni](https://cdn.letsmagic.cn/static/img/app-publishing.png) + +## 7. Capacità Enterprise e Commerciali 🏢 + +- **Collaborazione Team**: Supporto per la collaborazione team nello sviluppo congiunto di agenti intelligenti attraverso spazi team, e capacità di gestione collaborativa come gestione team, controllo autorizzazioni. +- **Versione Professionale**: Fornitura di soluzioni SaaS a pagamento, supporto per funzionalità e servizi più avanzati. +- **Pubblicazione API/SDK**: Supporto per la pubblicazione di agenti intelligenti come API o SDK, utilizzabili dagli utenti per chiamate secondarie. + +--- + # Magic - AI应用开发平台 ## 1. 实时聊天 @@ -21,7 +90,6 @@ Magic平台的企业内部聊天功能支持多人同时在线，操作界面简 ![AI助理列表](https://cdn.letsmagic.cn/static/img/ai-assistant-2.png) - ## 3. 工作流编排 - **流程编排**：通过拖拉拽的方式快速搭建工作流，处理逻辑复杂且有较高稳定性要求的任务流。 @@ -34,12 +102,10 @@ Magic平台的企业内部聊天功能支持多人同时在线，操作界面简 ![流程界面](https://cdn.letsmagic.cn/static/img/workflow-process.png) - ### 工具集 ![工具集界面](https://cdn.letsmagic.cn/static/img/tools.png) - ## 4. 记忆功能 - **长期记忆**：提供变量、数据库、文件等记忆功能，使Bot具备长期记忆能力。 @@ -49,8 +115,6 @@ Magic平台的企业内部聊天功能支持多人同时在线，操作界面简 ![数据库记忆界面](https://cdn.letsmagic.cn/static/img/memory-2.png) - - ## 5. 多模态交互 - **多种交互方式**：支持文本、语音、图像等多种交互方式，提供更加丰富的用户体验。 @@ -58,16 +122,12 @@ Magic平台的企业内部聊天功能支持多人同时在线，操作界面简 ![多模态交互界面](https://cdn.letsmagic.cn/static/img/multimodal.png) - - ## 6. 应用发布 - **多平台发布**：支持将开发的AI应用发布到企微、钉钉等多个平台。 ![应用发布界面](https://cdn.letsmagic.cn/static/img/app-publishing.png) - - ## 7. 企业版和商业化能力 - **团队协作**：通过团队空间支持团队协作共同开发智能体，以及团队管理、权限控制等协作管理能力。 diff --git a/docs/zh/tutorial/magic-info/index.md b/docs/zh/tutorial/magic-info/index.md index 9ecb35d2e..11c41c2fd 100644 --- a/docs/zh/tutorial/magic-info/index.md +++ b/docs/zh/tutorial/magic-info/index.md @@ -1,3 +1,81 @@ +# Magic - Piattaforma di Sviluppo Applicazioni AI + +Magic è una piattaforma di sviluppo applicazioni AI enterprise-level che fornisce alle aziende una soluzione completa dalla creazione di assistenti AI al deployment multipiattaforma. Di seguito sono presentate le funzionalità e caratteristiche principali della piattaforma: + +## Panoramica delle Funzionalità Principali + +### 1. Chat in Tempo Reale e Collaborazione + +La piattaforma fornisce un'interfaccia intuitiva simile a WeChat, supportando la comunicazione simultanea di più utenti, inclusi chat private e discussioni di gruppo. Le potenti funzionalità di gestione dei gruppi permettono agli amministratori di assegnare flessibilmente le autorizzazioni ai diversi membri, migliorando l'efficienza della comunicazione interna aziendale. + +![Interfaccia Chat in Tempo Reale](https://cdn.letsmagic.cn/static/img/20250512164817.jpg) + +### 2. Creazione e Gestione Assistenti AI + +- **Costruzione Zero-Codice**: Senza bisogno di basi di programmazione, è possibile creare assistenti AI intelligenti attraverso un'interfaccia visuale +- **Gestione Versioni**: Supporta il rilascio di versioni degli assistenti, controllo dello stato abilitato/disabilitato +- **Pubblicazione Interna Aziendale**: Facilita la condivisione dell'elenco degli assistenti AI all'interno dell'azienda + +![Interfaccia Gestione Assistenti AI](https://cdn.letsmagic.cn/static/img/20250512164212.jpg) + +### 3. Sistema di Orchestrazione Workflow + +- **Design Drag-and-Drop**: Costruisci rapidamente workflow attraverso il drag-and-drop per gestire compiti logici complessi +- **Componenti Nodo Ricchi**: Fornisce vari nodi come modelli di linguaggio di grandi dimensioni, codice personalizzato, logica di giudizio +- **Controllo del Flusso**: Supporta controllo del flusso di base come nodi di inizio, risposta, attesa e fine +- **Supporto Template**: Template workflow integrati per ridurre la soglia di utilizzo + +![Interfaccia Orchestrazione Workflow](https://cdn.letsmagic.cn/static/img/workflow-1.png) + +### 4. Knowledge Base e Funzionalità di Memoria + +- **Capacità di Memoria a Lungo Termine**: Realizza la memoria a lungo termine degli assistenti AI attraverso variabili, database, file +- **Integrazione Knowledge Base**: Supporta l'importazione di documenti aziendali e knowledge base per migliorare l'accuratezza delle risposte AI +- **Memoria Database**: Capacità di memoria database conveniente per ricordare persistentemente contenuti importanti nelle conversazioni utente + +![Interfaccia Funzionalità Memoria](https://cdn.letsmagic.cn/static/img/memory-1.png) + +### 5. Esperienza di Interazione Multimodale + +- **Modalità di Interazione Multiple**: Supporta varie modalità di interazione come testo, voce, immagini +- **Creazione Creativa**: Gli utenti possono utilizzare funzioni come generazione immagini AI, ritratti AI per lavori creativi + +![Interfaccia Interazione Multimodale](https://cdn.letsmagic.cn/static/img/multimodal.png) + +### 6. Pubblicazione Applicazioni Multipiattaforma + +- **Deployment Multipiattaforma**: Supporta la pubblicazione delle applicazioni AI sviluppate su multiple piattaforme come WeChat aziendale, DingTalk +- **Pubblicazione API/SDK**: Pubblica gli agenti intelligenti come API o SDK per l'utilizzo secondario da parte degli utenti + +![Interfaccia Pubblicazione Applicazioni](https://cdn.letsmagic.cn/static/img/app-publishing.png) + +## Casi di Best Practice + +### Assistente Conoscenze Punto Vendita + +Attraverso l'integrazione delle conoscenze relative al punto vendita, crea un assistente AI capace di rispondere alle domande quotidiane dei dipendenti, coprendo aspetti come gestione dispositivi, operazioni sistema di cassa, servizio post-vendita, migliorando l'efficienza del lavoro dei dipartimenti di supporto. + +### Assistente Approvazioni Magic + +Realizza la funzionalità "avvia approvazione con una frase", completando revisioni intelligenti e decisioni automatiche attraverso tecnologia AI, aumentando significativamente l'efficienza delle approvazioni e riducendo l'intervento manuale. + +### Realizza Compiti Complessi con una Frase + +Attraverso la collaborazione di molteplici Agent (Agent di Pensiero, Agent di Suddivisione Compiti, Agent di Esecuzione Compiti), realizza compiti di gestione progetti complessi con un solo comando dell'utente. + +## Funzionalità Enterprise e Valore Commerciale + +- **Collaborazione Team**: Supporta la collaborazione team per lo sviluppo congiunto di agenti intelligenti attraverso spazi team +- **AI FLOW**: Utilizza AI per accelerare l'implementazione del FLOW, dalla creatività al lancio richiede in media solo 3.2 giorni, risparmiando il 78% dei costi di manodopera rispetto allo sviluppo FLOW tradizionale +- **Servizio Professional**: Fornisce soluzioni SaaS a pagamento, supportando più funzionalità e servizi avanzati +- **Super Magic**: Basandosi su algoritmi AI avanzati, comprende profondamente l'intento di ricerca, recupera rapidamente knowledge base aziendali, documenti e informazioni web, formando rapporti di ricerca approfondita + +La piattaforma Magic rende lo sviluppo di applicazioni AI semplice ed efficiente. Che abbiate o meno basi di programmazione, potrete costruire rapidamente le applicazioni intelligenti necessarie alla vostra azienda, elevando il livello di digitalizzazione e intelligenza dell'azienda. + +--- + +## 中文原文 + # Magic - AI 应用开发平台 Magic是一个企业级AI应用开发平台，为企业提供了从AI助手创建到多平台部署的完整解决方案。以下是平台的核心功能和特性： diff --git a/docs/zh/tutorial/magic-info/names.md b/docs/zh/tutorial/magic-info/names.md index 5b70291b7..216a78fd6 100644 --- a/docs/zh/tutorial/magic-info/names.md +++ b/docs/zh/tutorial/magic-info/names.md @@ -1,58 +1,108 @@ -# 名称解释 -本文阐释了在 Magic 中所使用的核心术语与重要概念。 +# Spiegazione Nomi 📚 -## 基础概念 +Questo articolo spiega i termini core e i concetti importanti utilizzati in Magic. +## Concetti Fondamentali 🧠 +| Termine | Descrizione | +| ------- | ----------- | +| Modello (Model) | Il modello contiene numerosi parametri ed è addestrato su grandi quantità di dati diversi. Puoi utilizzare il modello per eseguire vari compiti, come generazione immagini, domande e risposte, generazione codice, riscrittura, ecc. | +| Chiave di Accesso (Access Token) | Quando si chiama Magic API e SDK, è necessario verificare l'identità utente e autorizzare attraverso la chiave di accesso. Gli utenti possono impostare diverse autorizzazioni per ciascuna chiave di accesso, realizzando l'accesso sicuro alle risorse. | +| Token | Nei modelli di linguaggio di grandi dimensioni, il token è l'unità fondamentale di elaborazione del testo, il modello solitamente divide il testo di input in una serie di token, poi elabora e analizza questi token. Il token può essere una parola, un carattere, un frammento di subword o altre forme di frammento di testo, il modo specifico di divisione dipende dall'algoritmo di tokenizzazione utilizzato dal modello, quindi il calcolo e il modo di elaborazione del token possono variare a seconda dell'architettura specifica e del design del modello. Quando si conversa con l'assistente AI, i Token prodotti sono la somma dei token di input e dei token di output. | +| Prompt (Prompt) | Istruzioni in linguaggio naturale che dicono al modello di eseguire compiti. Ad esempio, "Traduci il testo in inglese".
Si consiglia di specificare il ruolo del modello, progettare lo stile linguistico delle risposte, limitare l'ambito delle risposte del modello nella configurazione personaggio e logica di risposta, rendendo la conversazione più conforme alle aspettative dell'utente. | +| Workflow (Workflow) | Il workflow è uno strumento utilizzato per pianificare e implementare logica funzionale complessa. Puoi progettare compiti multi-step complessi trascinando diversi nodi di compito, migliorando l'efficienza di costruzione in scenari aziendali complessi. | +| Knowledge Base (Knowledge) | La knowledge base è una raccolta privata di conoscenza dell'assistente AI, utilizzata per memorizzare dati di conoscenza in campi professionali, risolvendo il problema dell'insufficienza di conoscenza in campi professionali dei modelli generici di grandi dimensioni, migliorando la professionalità e l'accuratezza delle risposte dell'assistente AI. | +| Memoria | La memoria si riferisce alla capacità dell'intelligenza artificiale di memorizzare, recuperare e utilizzare informazioni nel tempo, migliorando le prestazioni del modello fornendo risposte più accurate e contestuali.
Magic fornisce una serie di funzionalità di memoria, inclusi variabili, database e memoria a lungo termine, per soddisfare diversi casi d'uso. Sulla base di queste memorie possono essere fornite risposte personalizzate, migliorando l'esperienza utente. | -| 术语 | 描述 | -| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 模型（Model） | 模型包含大量参数，并基于大量不同的数据进行训练。您可以使用模型执行各种任务，如图像生成、问答、代码生成、重写等。 | -| 访问密钥（Access Token） | 调用 Magic API 和 SDK 时，需要通过访问密钥验证用户身份、鉴权。用户可以为各个访问密钥设置不同的权限，实现资源的安全访问。 | -| Token | 在大语言模型中，token 是文本处理的基本单位，模型通常将输入文本分解成一系列 token，然后对这些 token 进行处理和分析。token 可以是单词、字符、子词片段或其他形式的文本片段，具体的划分方式取决于模型使用的分词算法，所以 token 的计算和处理方式可能会根据模型的具体架构和设计而有所不同。和AI 助理对话时，产生的 Token 为输入 token 和输出 token 之和。 | -| 提示词 (Prompt) | 告诉模型执行任务的自然语言指令。例如，“将文本翻译成英文”。
建议在人设与回复逻辑中指定模型的角色、设计回复的语言风格、限制模型的回答范围，让对话更符合用户预期。 | -| 工作流（Workflow） | 工作流是一种用于规划和实现复杂功能逻辑的工具。你可以通过拖拽不同的任务节点来设计复杂的多步骤任务，提升复杂业务场景下的搭建效率。 | -| 知识库（Knowledge） | 知识库是AI 助理的私有知识合集，用于存储专业领域的知识数据，解决通用大模型专业领域知识不足的问题，提高AI 助理回复的专业性和准确性。 | -| 记忆 | 记忆是指人工智能随着时间的推移存储、检索和利用信息的能力，通过提供更准确、更符合语境的响应来提高模型的性能。
麦吉提供了一组记忆功能，包括变量、数据库和长期记忆，以满足不同的用例。基于这些记忆可以提供个性化回复，提升用户体验。 | +## Nomi dei Nodi 🔧 -## 节点名称 +| Categoria | Nome Nodo | Spiegazione Nodo | +| --------- | --------- | --------------- | +| Base | Nodo Inizio | Quando viene attivato il seguente evento, il flusso inizierà l'esecuzione da questo modulo | +| Base | Risposta Messaggio | Rispondi o rispondi con contenuto specificato all'utente | +| Base | Nodo Fine | Nodo finale del flusso, utilizzato per restituire le informazioni sui risultati dopo l'esecuzione del workflow | +| Base | Attesa | Il flusso attenderà l'operazione successiva dell'utente in questo nodo | +| Modello Grande | Chiamata Modello Grande | Chiama il modello di linguaggio di grandi dimensioni, utilizza variabili e prompt per generare risposte | +| Modello Grande | Riconoscimento Intento | Il modello grande riconosce l'intento effettivo del contenuto basato sul contenuto di input | +| Operazione | Selettore | Connette più rami downstream, se la condizione impostata è vera esegue il ramo "corrispondente", altrimenti esegue il ramo "altrimenti" | +| Operazione | Esecuzione Codice | Scrivi codice per elaborare le variabili di input, poi genera valori di ritorno attraverso l'output | +| Operazione | Richiesta HTTP | Invia richiesta al servizio HTTP esterno secondo i parametri impostati e ottieni i dati di risposta | +| Operazione | Sottoprocesso | Assegna moduli funzionali parziali all'orchestrazione del sottoprocesso, evitando che il processo principale diventi troppo grande | +| Operazione | Strumento | Processo strumento riutilizzabile, trasferisce parte delle funzionalità del processo all'implementazione dello strumento | +| Operazione | Ricerca Personale | Cerca informazioni personali che soddisfano le condizioni, supporta solo la visualizzazione di persone e informazioni correlate visibili al parlante | +| Operazione | Ciclo | Ripete l'esecuzione di una serie di compiti impostando il numero di cicli e la logica | +| Operazione | Ricerca Conoscenza | Effettua ricerca conoscenza sulle parole chiave di input, restituisce contenuti correlati corrispondenti | +| Operazione | Analisi Documento Cloud | Output del contenuto del documento cloud specificato in struttura Markdown attraverso il nodo | +| Operazione | Generazione Immagini | Genera immagini attraverso descrizioni testuali | +| Operazione | Crea Chat di Gruppo | Crea una chat di gruppo contenente i membri del gruppo specificati | +| Elaborazione Dati | Query Messaggi Storici | Query messaggi storici secondo condizioni specificate | +| Elaborazione Dati | Archiviazione Messaggi Storici | Memoria archiviazione personalizzata, libera scelta di archiviare qualsiasi contenuto | +| Knowledge Base Vettoriale | Archiviazione Vettoriale | Archivia nella knowledge base in forma di frammenti | +| Knowledge Base Vettoriale | Ricerca Vettoriale | Effettua matching di similarità dall'alto verso il basso in molteplici knowledge base, output frammenti con similarità e quantità specificate | +| Knowledge Base Vettoriale | Eliminazione Vettoriale | Effettua matching di similarità dall'alto verso il basso in molteplici knowledge base, output frammenti con similarità e quantità specificate | +| Knowledge Base Vettoriale | Matching Knowledge Base Vettoriale | Matching knowledge base vettoriali correlate attraverso condizioni di query | +| Database Persistente | Archiviazione Dati | Archivia dati persistenti | +| Database Persistente | Caricamento Dati | Leggi dati persistenti | +| Variabili | Salvataggio Variabili | Se la variabile esiste la aggiorna, se non esiste la crea nuova | +| Magic Table | Nuovo Record | Aggiungi nuovo record alla tabella dati specificata | +| Magic Table | Modifica Record | Modifica record della tabella dati specificata | +| Magic Table | Query Record | Query righe record della tabella dati secondo condizioni specificate | +| Magic Table | Elimina Record | Elimina righe record della tabella dati secondo condizioni specificate | +| Correlato File | Analisi Documento | Estrai contenuto testo del file, output in forma testo per l'uso del prossimo nodo | +| Correlato File | Analisi Foglio Elettronico | Estrai contenuto testo del file, output in forma testo per l'uso del prossimo nodo | +| Correlato Testo | Taglio Testo | Taglia testi lunghi secondo strategia stabilita, in futuro sarà aperta la selezione strategia | +--- +# 名称解释 +本文阐释了在 Magic 中所使用的核心术语与重要概念。 + +## 基础概念 +| 术语 | 描述 | +| ---- | ---- | +| 模型（Model） | 模型包含大量参数，并基于大量不同的数据进行训练。您可以使用模型执行各种任务，如图像生成、问答、代码生成、重写等。 | +| 访问密钥（Access Token） | 调用 Magic API 和 SDK 时，需要通过访问密钥验证用户身份、鉴权。用户可以为各个访问密钥设置不同的权限，实现资源的安全访问。 | +| Token | 在大语言模型中，token 是文本处理的基本单位，模型通常将输入文本分解成一系列 token，然后对这些 token 进行处理和分析。token 可以是单词、字符、子词片段或其他形式的文本片段，具体的划分方式取决于模型使用的分词算法，所以 token 的计算和处理方式可能会根据模型的具体架构和设计而有所不同。和AI 助理对话时，产生的 Token 为输入 token 和输出 token 之和。 | +| 提示词 (Prompt) | 告诉模型执行任务的自然语言指令。例如，"将文本翻译成英文"。
建议在人设与回复逻辑中指定模型的角色、设计回复的语言风格、限制模型的回答范围，让对话更符合用户预期。 | +| 工作流（Workflow） | 工作流是一种用于规划和实现复杂功能逻辑的工具。你可以通过拖拽不同的任务节点来设计复杂的多步骤任务，提升复杂业务场景下的搭建效率。 | +| 知识库（Knowledge） | 知识库是AI 助理的私有知识合集，用于存储专业领域的知识数据，解决通用大模型专业领域知识不足的问题，提高AI 助理回复的专业性和准确性。 | +| 记忆 | 记忆是指人工智能随着时间的推移存储、检索和利用信息的能力，通过提供更准确、更符合语境的响应来提高模型的性能。
麦吉提供了一组记忆功能，包括变量、数据库和长期记忆，以满足不同的用例。基于这些记忆可以提供个性化回复，提升用户体验。 | +## 节点名称 -| 类别 | 节点名称 | 节点说明 | -| ------------ | -------------- | ------------------------------------------------------------------------ | -| 基础 | 开始节点 | 当以下事件被触发时，流程将会从这个模块开始执行 | -| 基础 | 消息回复 | 回复或回复一段指定内容给用户 | -| 基础 | 结束节点 | 流程的最终节点，用于返回工作流程运行后的结果信息 | -| 基础 | 等待 | 流程将在此节点等待用户下一步操作 | -| 大模型 | 大模型调用 | 调用大语言模型，使用变量和提示词生成回复 | -| 大模型 | 意图识别 | 大模型根据输入的内容识别内容实际的意图 | -| 操作 | 选择器 | 连接多个下游分支，若设定条件成立则运行“对应”分支，不成立则运行“否则”分支 | -| 操作 | 代码执行 | 编写代码处理输入变量，再通过输出生成返回值 | -| 操作 | HTTP 请求 | 根据设定参数向外部 HTTP 服务发送请求并获取响应数据 | -| 操作 | 子流程 | 将部分功能模块分配给子流程编排，避免主流程过于庞大 | -| 操作 | 工具 | 可复用工具流程，将部分流程功能转交给工具实现 | -| 操作 | 人员检索 | 查找符合条件的人员信息，仅支持查看对话者可见的人员及相关信息 | -| 操作 | 循环 | 通过设定循环次数和逻辑，重复执行一系列任务 | -| 操作 | 知识检索 | 对输入关键词进行知识检索，返回匹配的相关内容 | -| 操作 | 云文档解析 | 通过节点将指定云文档以 Markdown 结构输出内容 | -| 操作 | 图像生成 | 通过文字描述生成图片 | -| 操作 | 创建群聊 | 创建包含指定群成员的群聊 | -| 数据处理 | 历史消息查询 | 根据指定条件查询历史消息 | -| 数据处理 | 历史消息存储 | 记忆自定义存储，自由选择存储任何内容 | -| 向量知识库 | 向量存储 | 以片段形式存储到知识库 | -| 向量知识库 | 向量搜索 | 在多个知识库中从上到下进行相似度匹配，输出指定相似度和数量的片段 | -| 向量知识库 | 向量删除 | 在多个知识库中从上到下进行相似度匹配，输出指定相似度和数量的片段 | -| 向量知识库 | 向量知识库匹配 | 通过查询条件匹配相关的向量知识库 | -| 持久化数据库 | 数据存储 | 存储持久化数据 | -| 持久化数据库 | 数据加载 | 读取持久化数据 | -| 变量 | 变量保存 | 变量存在则更新，不存在则新增 | -| 神奇表格 | 新增记录 | 向指定数据表新增记录 | -| 神奇表格 | 修改记录 | 修改指定数据表记录 | -| 神奇表格 | 查询记录 | 根据指定条件查询数据表的行记录 | -| 神奇表格 | 删除记录 | 根据指定条件删除数据表的行记录 | -| 文件相关 | 文档解析 | 提取文件文本内容，以文本形式输出至下一个节点使用 | -| 文件相关 | 电子表格解析 | 提取文件文本内容，以文本形式输出至下一个节点使用 | -| 文本相关 | 文本切割 | 按既定策略切割长文本，未来将开放策略选择 | +| 类别 | 节点名称 | 节点说明 | +| ---- | -------- | -------- | +| 基础 | 开始节点 | 当以下事件被触发时，流程将会从这个模块开始执行 | +| 基础 | 消息回复 | 回复或回复一段指定内容给用户 | +| 基础 | 结束节点 | 流程的最终节点，用于返回工作流程运行后的结果信息 | +| 基础 | 等待 | 流程将在此节点等待用户下一步操作 | +| 大模型 | 大模型调用 | 调用大语言模型，使用变量和提示词生成回复 | +| 大模型 | 意图识别 | 大模型根据输入的内容识别内容实际的意图 | +| 操作 | 选择器 | 连接多个下游分支，若设定条件成立则运行"对应"分支，不成立则运行"否则"分支 | +| 操作 | 代码执行 | 编写代码处理输入变量，再通过输出生成返回值 | +| 操作 | HTTP 请求 | 根据设定参数向外部 HTTP 服务发送请求并获取响应数据 | +| 操作 | 子流程 | 将部分功能模块分配给子流程编排，避免主流程过于庞大 | +| 操作 | 工具 | 可复用工具流程，将部分流程功能转交给工具实现 | +| 操作 | 人员检索 | 查找符合条件的人员信息，仅支持查看对话者可见的人员及相关信息 | +| 操作 | 循环 | 通过设定循环次数和逻辑，重复执行一系列任务 | +| 操作 | 知识检索 | 对输入关键词进行知识检索，返回匹配的相关内容 | +| 操作 | 云文档解析 | 通过节点将指定云文档以 Markdown 结构输出内容 | +| 操作 | 图像生成 | 通过文字描述生成图片 | +| 操作 | 创建群聊 | 创建包含指定群成员的群聊 | +| 数据处理 | 历史消息查询 | 根据指定条件查询历史消息 | +| 数据处理 | 历史消息存储 | 记忆自定义存储，自由选择存储任何内容 | +| 向量知识库 | 向量存储 | 以片段形式存储到知识库 | +| 向量知识库 | 向量搜索 | 在多个知识库中从上到下进行相似度匹配，输出指定相似度和数量的片段 | +| 向量知识库 | 向量删除 | 在多个知识库中从上到下进行相似度匹配，输出指定相似度和数量的片段 | +| 向量知识库 | 向量知识库匹配 | 通过查询条件匹配相关的向量知识库 | +| 持久化数据库 | 数据存储 | 存储持久化数据 | +| 持久化数据库 | 数据加载 | 读取持久化数据 | +| 变量 | 变量保存 | 变量存在则更新，不存在则新增 | +| 神奇表格 | 新增记录 | 向指定数据表新增记录 | +| 神奇表格 | 修改记录 | 修改指定数据表记录 | +| 神奇表格 | 查询记录 | 根据指定条件查询数据表的行记录 | +| 神奇表格 | 删除记录 | 根据指定条件删除数据表的行记录 | +| 文件相关 | 文档解析 | 提取文件文本内容，以文本形式输出至下一个节点使用 | +| 文件相关 | 电子表格解析 | 提取文件文本内容，以文本形式输出至下一个节点使用 | +| 文本相关 | 文本切割 | 按既定策略切割长文本，未来将开放策略选择 | diff --git a/docs/zh/tutorial/quick-start/build-a-bot/Key concepts.md b/docs/zh/tutorial/quick-start/build-a-bot/Key concepts.md index 836ac7e9a..77430ef31 100644 --- a/docs/zh/tutorial/quick-start/build-a-bot/Key concepts.md +++ b/docs/zh/tutorial/quick-start/build-a-bot/Key concepts.md @@ -1,3 +1,25 @@ +# 🔑 Concetti Chiave + +## 🧩 Nodi +I nodi sono componenti chiave del workflow. Connettendo nodi con diverse funzionalità, è possibile eseguire una serie di operazioni nel workflow. Per i nodi workflow core, fare riferimento alla documentazione nodi. + +## 📊 Variabili +Le variabili sono utilizzate per connettere input e output tra nodi nel workflow, implementando logica di elaborazione complessa nel processo. Include variabili ambiente e variabili sessione (pianificato supporto futuro). +![Concetti Chiave](https://cdn.letsmagic.cn/static/img/Key-concepts-1.png) + +--- +## 📝 Lista Versioni +Magic fornisce meccanismo di salvataggio online in tempo reale. Attraverso i record lista versioni, è possibile salvare le ultime modifiche in qualsiasi momento, facilitando la collaborazione e registrazione, prevenendo perdita dati. + +![Concetti Chiave](https://cdn.letsmagic.cn/static/img/Key-concepts-2.png) + +## ⚡ Comandi Rapidi +I comandi rapidi sono un modo efficiente di interazione, attraverso sequenze operative preimpostate o personalizzate, per attivare rapidamente funzionalità o compiti specifici. Forniamo metodi di impostazione efficienti, semplificando operazioni complesse in clic o comandi vocali (pianificato upgrade futuro). Possono essere impostati nella barra strumenti e finestra dialogo, aiutando gli utenti a superare colli di bottiglia efficienza, riducendo contemporaneamente la dipendenza da dettagli tecnici. + +![Concetti Chiave](https://cdn.letsmagic.cn/static/img/Key-concepts-3.png) + +--- + # 关键概念 ## 节点 diff --git a/docs/zh/tutorial/quick-start/build-a-bot/quick-build-AI-translation-assistant.md b/docs/zh/tutorial/quick-start/build-a-bot/quick-build-AI-translation-assistant.md index 5df7effed..1434ac126 100644 --- a/docs/zh/tutorial/quick-start/build-a-bot/quick-build-AI-translation-assistant.md +++ b/docs/zh/tutorial/quick-start/build-a-bot/quick-build-AI-translation-assistant.md @@ -1,3 +1,73 @@ +# ⚡ Costruzione Rapida Assistente AI Traduzione + +Con il continuo sviluppo delle tecnologie di intelligenza artificiale, i modelli linguistici di grandi dimensioni hanno mostrato prestazioni eccellenti in termini di qualità traduzione, efficienza, comprensione contesto e supporto multilingue. Pertanto, sempre più persone iniziano a utilizzare modelli grandi per costruire rapidamente i propri assistenti traduzione, utilizzati per traduzione testi, migliorando l'efficienza e riducendo i costi. + +Questo tutorial introdurrà in dettaglio come costruire rapidamente un assistente AI sulla piattaforma Magic. + +# 🤖 Introduzione Assistente Traduzione AI +Hai solo bisogno di impostare la lingua traduzione target nelle impostazioni assistente AI, poi puoi fornire direttamente il testo da tradurre all'assistente AI attraverso la conversazione. L'assistente AI restituirà direttamente la lingua tradotta dal modello grande, efficiente e veloce. +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-1.png) + +## 1. 🎯 Progettazione Effetto Previsto +La funzionalità core di questa applicazione traduzione AI è soddisfare le esigenze di traduzione testi degli utenti. Non necessita introduzioni testo aggiuntive, l'utente inserisce il contenuto da tradurre, restituisce direttamente il testo traduzione corrispondente. La funzionalità traduzione può essere realizzata creando workflow, includendo nodi modello grande. + +Basandosi sugli obiettivi scenario sopra, il workflow che progettiamo includerà i seguenti nodi: +1. Nodo input utente +2. Impostazione messaggio benvenuto assistente AI +3. Nodo che riceve input utente e traduce attraverso modello grande +4. Nodo che output contenuto traduzione + +## 2. 🛠️ Creazione Assistente Traduzione AI +1. Accedi alla piattaforma [Magic](https://www.letsmagic.cn/login). (Se utilizzi deployment privato, accedi alla corrispondente piattaforma deployment privato) +2. Clicca sul menu laterale sinistro "Assistente AI", poi clicca su "Crea Assistente AI" a destra +3. Carica immagine assistente, compila nome e introduzione assistente +4. Clicca "Crea", entra con successo nell'interfaccia orchestrazione workflow assistente AI +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-2.png) + +## 3. 🔄 Orchestrazione Workflow +### 1. Clicca crea "Nodo Iniziale" +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-3.png) + +### 2. Nell'area "Quando aggiungi come amico", clicca "cerchietto piccolo" aggiungi nodo risposta messaggio, aggiungi messaggio benvenuto corrispondente +> Ciao @Nodo Iniziale/Nickname Utente, +Sono il tuo assistente traduzione inglese dedicato. Puoi dirmi direttamente qualsiasi testo necessiti traduzione, ti fornirò la traduzione localizzata più autentica il più velocemente possibile. + +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-4.png) + +### 3. Quando ricevi nuovo messaggio aggiungi "Nodo Chiamata Modello Grande" +3.1. Nell'area modello, seleziona nodo modello grande supportato, altri parametri rimangono invariati, contemporaneamente attiva capacità comprensione visiva (selezione predefinita GPT-4) +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-5.png) + +3.2. Nell'area input, nel campo System compila il prompt del modello grande, nell'area User attraverso @ cita il contenuto utente del nodo precedente +``` +#Ruolo +Sei un traduttore inglese professionale, capace di tradurre accuratamente qualsiasi contenuto inserito dall'utente in inglese, senza espansioni arbitrarie. +##Abilità +###Abilità 1: Traduzione Testo +- Quando l'utente fornisce un testo, traducilo rapidamente in inglese. +- Garantisci accuratezza e fluidità della traduzione. Rendi la traduzione più localizzata possibile. +- Qualsiasi lingua va bene, sia cinese, giapponese, malese, thailandese ecc., necessitano traduzione in inglese secondo la semantica. +##Limitazioni: +- Esegui solo lavoro traduzione, non rispondere a domande non correlate alla traduzione. +- Segui rigorosamente la lingua target richiesta dall'utente, non modificare arbitrariamente. +``` +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-6.png) + +### 4. Aggiungi Nodo Risposta Messaggio +4.1 Seleziona tipo messaggio come "Testo", nel contenuto messaggio attraverso @ cita il contenuto risposta modello grande restituito all'utente +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-7.png) + +### 5. Pubblica Assistente +La pubblicazione è divisa in "Uso Personale" e "Interno Aziendale". La differenza sta nel fatto che uso personale è visibile utilizzabile solo da sé, mentre pubblicazione interno aziendale supporta più gestione permessi, come record numero versione, impostazione ambito visibilità, pubblicazione su piattaforme terze ecc. Questa volta pubblica selezionando direttamente "Uso Personale". +5.1 Puoi conversare direttamente con l'assistente AI, ti aiuta rapidamente a tradurre diverse lingue in inglese +![Screenshot Traduzione](https://cdn.letsmagic.cn/static/img/Translation-assistant-8.png) + +## 4. 📋 Importanti Spiegazioni +### 1. Cosa sono i Prompt Sistema? +I prompt sistema sono una serie di istruzioni che guidano il comportamento e l'ambito funzionale del modello. Possono includere come porre domande, come fornire informazioni, come richiedere funzionalità specifiche ecc. I prompt sistema sono anche utilizzati per impostare i confini della conversazione, come informare l'utente su quali tipi di domande o richieste non vengono accettate. + +--- + # 快速构建 AI 翻译助手 随着人工智能技术的不断发展，大语言模型在翻译质量、效率、上下文理解以及多语言支持方面都展现出了出色的表现。因此，越来越多的人开始使用大模型快速构建自己的翻译助手，用于文本翻译，提高效率，降低成本。 diff --git a/docs/zh/tutorial/quick-start/build-a-bot/quickly-build-an-agent.md b/docs/zh/tutorial/quick-start/build-a-bot/quickly-build-an-agent.md index 0087364d9..31ef70c4b 100644 --- a/docs/zh/tutorial/quick-start/build-a-bot/quickly-build-an-agent.md +++ b/docs/zh/tutorial/quick-start/build-a-bot/quickly-build-an-agent.md @@ -1,3 +1,87 @@ +# 🚀 Costruisci Rapidamente il Tuo Primo Assistente AI + +Che tu abbia o meno esperienza di programmazione, puoi costruire rapidamente un assistente AI sulla piattaforma Magic. Questo articolo mostra come costruire un semplice assistente AI "Nutrizionista Intelligente" partendo da zero. + +## 🤖 Demo dell'Assistente AI + +![Demo](https://cdn.letsmagic.cn/static/img/20250512165243.jpg) + +## 📋 Passi per la Costruzione +Segui questi passi per costruire rapidamente un assistente AI. + +### 🎯 Creazione dell'Assistente AI +1. Accedi a [Magic](https://www.letsmagic.cn/) e clicca sul menu laterale "AI Assistant" +2. Clicca sul pulsante "Crea AI Assistant" in alto a destra della pagina +![Crea Assistente](https://cdn.letsmagic.cn/static/img/20250512164212.jpg) + +3. Inserisci le informazioni dell'assistente AI e clicca su crea +- Caricamento avatar: Seleziona un'immagine appropriata come avatar dell'assistente (dimensioni consigliate: 1024 × 1024 pixel). Se non carichi nulla, verrà utilizzato l'avatar predefinito. +- Nome: Magic Nutrizionista +- Descrizione: Un consulente alimentare personale che può pianificare scientificamente ogni pasto in base alle abitudini alimentari e alle esigenze dell'utente, gestire con precisione l'assunzione di ogni nutriente, aiutare l'utente a stabilire uno stile di vita sano. + +![Informazioni Assistente](https://cdn.letsmagic.cn/static/img/assistant-info.png) + +L'assistente AI è stato creato con successo, ma non ha ancora alcuna capacità. Iniziamo ad assegnargli delle capacità. + +### 💬 Configurazione del Messaggio di Benvenuto +Vogliamo che l'utente riceva un "messaggio di benvenuto" quando aggiunge "Magic Nutrizionista" e capisca come utilizzarlo. +Il metodo è il seguente: +1. Trascina il "nodo iniziale" dalla barra degli strumenti o clicca sul pulsante ➕ +![Nodo Iniziale](https://cdn.letsmagic.cn/static/img/start-node.png) +2. Clicca sul piccolo cerchio di "quando viene aggiunto come amico", seleziona il nodo di risposta messaggio +![Messaggio Benvenuto](https://cdn.letsmagic.cn/static/img/welcome-message.png) +3. Scrivi il saluto nel nodo di risposta messaggio +Saluto: Sono il tuo consulente alimentare personale, pianifico scientificamente ogni pasto, gestisco con precisione l'assunzione di ogni nutriente, insieme costruiamo uno stile di vita sano, facciamo sì che l'alimentazione diventi l'arte di nutrire la vita. Puoi dirmi: "Peso 60kg, altezza 160cm, voglio perdere 10kg, aiutami a pianificare una dieta equilibrata per tre pasti al giorno." +![Contenuto Benvenuto](https://cdn.letsmagic.cn/static/img/welcome-content.png) + +### 🧠 Creazione del Nodo Modello Grande e Scrittura del Prompt +1. Aggiungi un nodo di chiamata modello grande per "quando riceve messaggio" +![Nodo Modello Grande](https://cdn.letsmagic.cn/static/img/llm-node.png) +2. Scrivi il prompt, imposta ruolo e abilità per il modello grande +![Modifica Prompt](https://cdn.letsmagic.cn/static/img/prompt-edit.png) + +Mantieni le altre impostazioni invariate per ora. Il prompt è il seguente: +``` +Sei un consulente alimentare personale che può pianificare scientificamente ogni pasto in base alle abitudini alimentari e alle esigenze dell'utente, gestire con precisione l'assunzione di ogni nutriente, aiutare l'utente a stabilire uno stile di vita sano. +Le tue responsabilità includono: +Fornire consigli alimentari scientificamente ragionevoli e piani nutrizionali personalizzati in base alle condizioni fisiche dell'utente, obiettivi di salute (come perdita di peso, aumento muscolare, prevenzione), abitudini di vita, preferenze di gusto, ecc., per realizzare la personalizzazione del piano nutrizionale. Effettuare analisi nutrizionali precise di vari ingredienti e piatti, aiutare l'utente a comprendere il valore energetico e il contenuto di microelementi dei cibi assunti, condurre analisi nutrizionali degli alimenti. Assistere l'utente nella registrazione dell'alimentazione quotidiana e fornire valutazioni e feedback in tempo reale sulla struttura alimentare e sull'assunzione di nutrienti, assicurando che soddisfi le esigenze di salute personale, condurre registrazione e valutazione alimentare. Fornire servizi di consulenza professionale per problemi nutrizionali e esigenze alimentari speciali dell'utente (come dieta per diabetici, dieta in gravidanza, integrazione nutrizionale vegetariana), rispondere a consulenze sanitarie. Pubblicare regolarmente ricettari salutari diversificati e fornire guide dettagliate sui metodi e i passi di cottura, condurre raccomandazioni di ricettari e guide alla preparazione. Monitorare a lungo termine i cambiamenti nei dati di salute dell'utente, generare rapporti periodici per aiutare l'utente a comprendere i miglioramenti nella propria condizione nutrizionale e regolare le strategie alimentari, condurre monitoraggio delle tendenze sanitarie. Diffondere conoscenze nutrizionali attraverso modalità interattive, migliorare la cultura sanitaria dell'utente, coltivare buone abitudini alimentari, condurre apprendimento interattivo ed educazione. +Nel processo creativo, devi rispettare rigorosamente le leggi sul copyright e i principi etici. Dovresti assicurarti che tutte le opere siano originali, senza violare i diritti di proprietà intellettuale o la privacy di nessuno. Evita di utilizzare o imitare lo stile o le opere di qualsiasi artista noto, assicurati che la tua creazione sia indipendente, evita contenuti che potrebbero causare controversie. +``` +1. Crea un nodo di risposta per il modello grande +![Risposta Modello Grande](https://cdn.letsmagic.cn/static/img/llm-reply.png) +2. Nell'editor del contenuto del messaggio, fai riferimento alla risposta del modello grande +- Inserisci il simbolo "@", quando appaiono le opzioni, scorri fino in fondo e seleziona il nodo di risposta del modello grande +![Riferimento Modello](https://cdn.letsmagic.cn/static/img/model-reference.png) + +L'effetto finale è il seguente: +![Flusso Finale](https://cdn.letsmagic.cn/static/img/final-flow.png) + +### 🔧 Debug dell'Assistente +1. Clicca su "Test Run" in alto a destra +![Esecuzione Debug](https://cdn.letsmagic.cn/static/img/debug-run.png) +2. Inserisci i parametri di debug: "Ho carenza di vitamina C, raccomandami una ricetta salutare" e clicca su conferma +![Parametri Debug](https://cdn.letsmagic.cn/static/img/debug-params.png) +3. Osserva l'effetto - puoi vedere che il nodo di output mostra i suggerimenti di ricette forniti dal modello grande + +![Output Debug](https://cdn.letsmagic.cn/static/img/debug-output.png) + +> Se non sei soddisfatto, puoi modificare ripetutamente il prompt e testare l'esecuzione per il debug. + +### 🚀 Pubblicazione +1. Clicca sul pulsante di pubblicazione in alto a destra +![Esecuzione Debug](https://cdn.letsmagic.cn/static/img/debug-run.png) +2. Seleziona "Uso Personale" +![Pulsante Pubblicazione](https://cdn.letsmagic.cn/static/img/publish-button.png) +3. Clicca su "Chatta con AI Assistant" +![Chatta con AI](https://cdn.letsmagic.cn/static/img/chat-with-ai.png) +4. Si apre una nuova finestra di chat, puoi iniziare a chattare con il modello nella casella di input +![Finestra Chat](https://cdn.letsmagic.cn/static/img/chat-window.png) +> Se vuoi modificare nuovamente l'assistente AI, puoi nella pagina: clicca "AI Assistant" -> "Gestisci AI Assistant" in alto a destra -> trova il robot che hai appena creato + +🎉 Congratulazioni! Hai completato la creazione del tuo primo assistente AI. + +--- + # 快速构建你的第一个 AI 助手 无论你是否具备编程经验，都可以在 Magic 平台上快速构建一个 AI 助手。本文以"智能营养师"助手为例，展示如何从零开始构建一个简单的 AI 助手。 diff --git a/docs/zh/tutorial/quick-start/build-a-bot/tools/build-a-tool.md b/docs/zh/tutorial/quick-start/build-a-bot/tools/build-a-tool.md index f5ba83ecb..752c3ae33 100644 --- a/docs/zh/tutorial/quick-start/build-a-bot/tools/build-a-tool.md +++ b/docs/zh/tutorial/quick-start/build-a-bot/tools/build-a-tool.md @@ -1,29 +1,37 @@ -# 基本介绍 -【工具】与【子流程】实际上本质是一样的，只是用法和场景有所不同。 +# 🔧 Introduzione Base +【## 🛠️ Due, Creazione dell'Insieme di Strumenti Assistente Conoscenza +1. Accedi alla piattaforma [Magic](https://www.letsmagic.cn/login). (Se è un deployment privato, accedi alla piattaforma di login privata corrispondente) +2. Nella barra dei menu a sinistra clicca【AI Assistant】, a destra clicca【Crea Insieme Strumenti】 +3. Carica l'immagine dell'insieme strumenti e compila il nome dell'assistente e una semplice descrizione +4. Clicca【Insieme Strumenti Assistente Conoscenza】, a destra clicca【Aggiungi Strumento】 +5. Inserisci【srm_knowledge_search】, e aggiungi la descrizione corrispondente, come: "Recupera contenuti della knowledge base SRM" -【子流程】：一般用于拆分主流程，允许将主流程的一部分功能模块抽象成一个独立的工具能力，从而避免一个流程主体过大，进一步提升维护效率 +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-1.png) +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-2.png)】e【Sottoprocesso】sono in realtà essenzialmente la stessa cosa, solo che l'uso e gli scenari sono diversi. -【工具】：而工具一般用于被大模型调用，当然也允许以工具节点的形式存在 +【Sottoprocesso】: Generalmente utilizzato per suddividere il flusso principale, permette di astrarre una parte delle funzionalità del flusso principale in uno strumento indipendente, evitando che il corpo del flusso diventi troppo grande, migliorando ulteriormente l'efficienza di manutenzione -**对于「工具」有几种概念需要了解一下** +【Strumento】: Gli strumenti sono generalmente utilizzati per essere chiamati dai modelli grandi, ma possono anche esistere come nodi strumento -**系统自定义参数**：当工具作为工具节点的形式存在时，定义工具节点的自定义入参 +**Per quanto riguarda gli "strumenti" ci sono alcuni concetti da capire** -**大模型参数**：当被大模型调用时，定义大模型调用时的入参 +**Parametri personalizzati del sistema**: Quando lo strumento esiste come forma di nodo strumento, definisce i parametri di input personalizzati del nodo strumento -**输出**：工具调用完后返回的数据 +**Parametri del modello grande**: Quando viene chiamato dal modello grande, definisce i parametri di input durante la chiamata del modello grande -## 一、设计你想要得到的效果 -SRM 系统在实际的业务过程中使用广泛，用户需要频繁的去查找 SRM 知识库进行疑难解答，但是又不想重复设置多个 AI 助理，希望在一个 AI 助理上支持多个系统的知识问答，那么我们就需要将用户查找 SRM 知识库的能力抽象成一个独立的工具给大模型调用即可。 +**Output**: I dati restituiti dopo la chiamata dello strumento -基于以上的场景目标我们设计的工作流会包含以下几个部分： +## 🎯 Uno, Progetta l'Effetto che Vuoi Ottenere +Il sistema SRM è ampiamente utilizzato nei processi aziendali effettivi, gli utenti hanno frequentemente bisogno di cercare nella knowledge base SRM per risolvere problemi, ma non vogliono impostare ripetutamente più assistenti AI, sperano di supportare le domande e risposte di più sistemi su un singolo assistente AI, quindi abbiamo bisogno di astrarre la capacità dell'utente di cercare nella knowledge base SRM in uno strumento indipendente da chiamare per il modello grande. -1、创建一个知识助理工具集 +Basandoci sugli obiettivi di scenario sopra, il flusso di lavoro che progettiamo includerà le seguenti parti: -2、在对应的知识工具集下添加 **srm_knowledge_search** 工具 +1. Creare un insieme di strumenti assistente conoscenza -3、在对应的 AI 助理的【大模型节点】上配置上对应工具即可 +2. Nell'insieme di strumenti conoscenza corrispondente aggiungere lo strumento **srm_knowledge_search** + +3. Nel【nodo modello grande】dell'assistente AI corrispondente configurare lo strumento corrispondente ## 二、创建知识助理工具集 1. 登录 [Magic](https://www.letsmagic.cn/login)平台。（如果私有化部署则登录对应私有化登录平台） @@ -35,73 +43,74 @@ SRM 系统在实际的业务过程中使用广泛，用户需要频繁的去查 ![工具截图](https://cdn.letsmagic.cn/static/img/tool-1.png) ![工具截图](https://cdn.letsmagic.cn/static/img/tool-2.png) -## 三、编排工作流 -### 1、点击创建【开始节点】 -1.1 点击【添加参数】 +## ⚙️ Tre, Orchestrazione del Flusso di Lavoro +### 1. Clicca per creare【nodo iniziale】 +1.1 Clicca【Aggiungi Parametro】 -1.2 输入对应大模型参数输入内容如下图 +1.2 Inserisci il contenuto di input del parametro del modello grande come mostrato nell'immagine -![工具截图](https://cdn.letsmagic.cn/static/img/tool-3.png) +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-3.png) -### 2、连接并创建【向量搜索节点】 -2.1 选择知识库：固定值，选择供应链知识库 +### 2. Connetti e crea【nodo ricerca vettoriale】 +2.1 Seleziona knowledge base: valore fisso, seleziona knowledge base supply chain -2.2 搜索关键词：通过 @ 引用开始节点问题 +2.2 Parole chiave di ricerca: tramite @ riferimento alla domanda del nodo iniziale -2.3 元数据匹配：设置对应的参数值 +2.3 Corrispondenza metadati: imposta i valori dei parametri corrispondenti -（参数名：**knowledge_base_id**、参数值：**固定值、716406779765358592**） +(Parametro nome: **knowledge_base_id**, valore parametro: **valore fisso, 716406779765358592**) -![工具截图](https://cdn.letsmagic.cn/static/img/tool-4.png) +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-4.png) -### 3、连接并创建【大模型节点】 -3.1 模型区域，选择已支持的大模型节点，其他参数保持不变，同时也开启视觉理解能力（这里 默认选择 GPT-4o） +### 3. Connetti e crea【nodo modello grande】 +3.1 Area modello, seleziona il nodo modello grande supportato, altri parametri rimangono invariati, e attiva anche la capacità di comprensione visiva (qui seleziona GPT-4o per default) -![工具截图](https://cdn.letsmagic.cn/static/img/tool-5.png) +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-5.png) -3.2、输入区域， System 输入框填写输入给大模型的提示词，User 区域 通过 @引用**开始节点的问题**和**向量搜索节点的片段列表** +3.2 Area input, casella System compila il prompt da dare al modello grande, area User tramite @riferimento alla **domanda del nodo iniziale** e alla **lista frammenti del nodo ricerca vettoriale** -3.3、开启自动加载记忆 +3.3 Attiva caricamento automatico memoria ``` -#角色 -数据处理专家 -#任务 -根据给定问题选择关联性较高的若干片段，然后组织最恰当的答案。 -#目标 -答案要基于所选择的关联性较高的若干片段，在此基础上适当扩展，符合问题Q的逻辑，语法通顺流畅。 -#要求 -1、根据给定问题 Q，从fragment选项列表中选择最相关的若干个片段； -2、必须确保所选片段是和问题有关联的。如果你认为所有片段和问题都没有关联的话，查询不到相关信息。那么你就回答"检索不到该内容"； -3、回答不能生硬，可以适当根据答案润色一下，使得回答更通畅，但不得改变原答案的主旨； -4、如果所有fragment关联性都比较低的话，查询不到相关信息那么认为不存在答案，则输出"检索不到该内容"； -5、你的回答不能遗漏片段中的图片，需要一起展示渲染图片在你的回答内容中； - -#返回格式 -只返回答案；使用漂亮的 markdown 格式返回。 -#流程 -你需要严格按照以下流程思考并执行每一步： -1、接收一个问题（Q）； -2、从fragment列表中选择关联性较高的若干个片段；根据第二步选择的关联性较高的若干个片段，根据问题Q组织答案，并且返回； -3、答案可以稍加润色，使得语法通畅； +#Ruolo +Esperto di elaborazione dati +#Compito +In base alla domanda data, seleziona diversi frammenti con elevata correlazione, poi organizza la risposta più appropriata. +#Obiettivo +La risposta deve basarsi sui frammenti selezionati con elevata correlazione, estendendosi appropriatamente su questa base, essere conforme alla logica della domanda Q, grammaticalmente scorrevole. +#Requisiti +1. In base alla domanda Q data, seleziona i frammenti più rilevanti dalla lista opzioni frammenti; +2. Devi assicurarti che i frammenti selezionati siano correlati alla domanda. Se ritieni che tutti i frammenti non abbiano correlazione con la domanda, non è possibile recuperare informazioni rilevanti. Allora rispondi "Impossibile recuperare questo contenuto"; +3. La risposta non deve essere rigida, può essere leggermente ritoccata in base alla risposta per renderla più scorrevole, ma non deve cambiare l'essenza della risposta originale; +4. Se tutti i frammenti hanno bassa correlazione, non è possibile recuperare informazioni rilevanti quindi non esiste risposta, allora output "Impossibile recuperare questo contenuto"; +5. La tua risposta non deve omettere le immagini nei frammenti, deve mostrare insieme il rendering delle immagini nel tuo contenuto di risposta; + +#Formato di ritorno +Restituisci solo la risposta; usa un bel formato markdown. +#Flusso +Devi seguire rigorosamente il seguente flusso per pensare ed eseguire ogni passo: +1. Ricevi una domanda (Q); +2. Dalla lista frammenti seleziona diversi frammenti con elevata correlazione; +3. In base ai frammenti selezionati con elevata correlazione del passo 2, organizza la risposta in base alla domanda Q e restituisci; +4. La risposta può essere leggermente ritoccata per rendere la grammatica scorrevole; ``` -![工具截图](https://cdn.letsmagic.cn/static/img/tool-6.png) -### 4、连接并创建【结束节点】 -4.1、添加对应结束参数值（参数名：**response**、参数值：**固定值，并通过 @引用大模型文本字符串**） +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-6.png) +### 4. Connetti e crea【nodo finale】 +4.1 Aggiungi il valore del parametro finale corrispondente (nome parametro: **response**, valore parametro: **valore fisso, e tramite @riferimento alla stringa di testo del modello grande**) -![工具截图](https://cdn.letsmagic.cn/static/img/tool-7.png) +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-7.png) -### 5、工具发布 -5.1、点击发布，填上对应的版本命名和版本描述即可 +### 5. Pubblicazione strumento +5.1 Clicca pubblica, compila il nome versione corrispondente e la descrizione versione -![工具截图](https://cdn.letsmagic.cn/static/img/tool-8.png) +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-8.png) -### 6、AI 知识助理引用 +### 6. Riferimento assistente AI conoscenza -6.1、选择需要支持 SRM 问答的 AI 助理，在大模型节点点击【添加工具】 +6.1 Seleziona l'assistente AI che necessita di supportare le domande SRM, nel nodo modello grande clicca【Aggiungi Strumento】 -6.2、选择【知识助理工具集】，添加【srm_knowledge_search】工具，也可以通过搜索栏快速搜索 -![工具截图](https://cdn.letsmagic.cn/static/img/tool-9.png) -![工具截图](https://cdn.letsmagic.cn/static/img/tool-10.png) +6.2 Seleziona【Insieme Strumenti Assistente Conoscenza】, aggiungi lo strumento【srm_knowledge_search】, oppure puoi cercare rapidamente tramite barra di ricerca +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-9.png) +![Screenshot Strumento](https://cdn.letsmagic.cn/static/img/tool-10.png) --- -完成上述配置，对应的 AI 助理就能支持查询 SRM知识库的内容啦。 \ No newline at end of file +Dopo aver completato la configurazione sopra, l'assistente AI corrispondente potrà supportare l'interrogazione dei contenuti della knowledge base SRM. \ No newline at end of file diff --git a/docs/zh/tutorial/quick-start/manage-llm/llm2.md b/docs/zh/tutorial/quick-start/manage-llm/llm2.md index 7bdf9eec1..ee875eaa6 100644 --- a/docs/zh/tutorial/quick-start/manage-llm/llm2.md +++ b/docs/zh/tutorial/quick-start/manage-llm/llm2.md @@ -1,3 +1,59 @@ +## 🔍 Anteprima funzioni + +Attenzione: il pannello di amministrazione è in beta. Per ora configura i modelli tramite variabili d'ambiente: ../../../development/deploy/environment.md#_4-ai-模型配置 + +Se sei un super amministratore di organizzazione: clicca sull'avatar in alto a sinistra ⇒ entra nella console di amministrazione. + +![Fi-lguvpG_yCUWav8wIsw6lfvoYp.png](https://cdn.letsmagic.cn/static/img/Fi-lguvpG_yCUWav8wIsw6lfvoYp.png) + +## ☁️ Configurare Microsoft Azure +### 2.1 Inserisci l’endpoint API + +![FkV9KpWFwEU56B88zPK7nwdUeYil.png](https://cdn.letsmagic.cn/static/img/FkV9KpWFwEU56B88zPK7nwdUeYil.png) + +## 🪄 Configurare ByteDance Volcengine +### 3.1 Indirizzo API +https://ark.cn-beijing.volces.com/ + +![FioaPOfC3oc0bGaaWq78sgyd7_i1.png](https://cdn.letsmagic.cn/static/img/FioaPOfC3oc0bGaaWq78sgyd7_i1.png) + +### 3.2 Nome modello + +![Fn2GBfAUgc4AkK5SiGbmYj3x8kgj.png](https://cdn.letsmagic.cn/static/img/Fn2GBfAUgc4AkK5SiGbmYj3x8kgj.png) + +## 🧩 Provider personalizzato (compatibile OpenAI API) +### 4.1 Aggiungi un provider personalizzato + +![FvKLaK0LaSNSMYsVLDmpRBGbJ7Ad.png](https://cdn.letsmagic.cn/static/img/FvKLaK0LaSNSMYsVLDmpRBGbJ7Ad.png) + +### 4.2 Configura l’endpoint API +- Kimi LLM: https://api.moonshot.cn +- Baidu Qianfan: https://qianfan.baidubce.com/v2 + +![FtB1mFoFCiL3kAaqBh0x8yAYnBw8.png](https://cdn.letsmagic.cn/static/img/FtB1mFoFCiL3kAaqBh0x8yAYnBw8.png) + +### 4.3 Aggiungi i modelli corrispondenti + +![Fnf25GBXzCb_gnS1DtLSDLJOk-LR.png](https://cdn.letsmagic.cn/static/img/Fnf25GBXzCb_gnS1DtLSDLJOk-LR.png) + +## 🧠 Abilitare i modelli di embedding vettoriale +Esempio con Volcengine: +1) Introduzione agli embedding: https://www.volcengine.com/docs/82379/1302003 +2) Clic su “Vai al debug” + +![FsqFvaxlu7MiQB7Jg8zsgmlyBoeU.png](https://cdn.letsmagic.cn/static/img/FsqFvaxlu7MiQB7Jg8zsgmlyBoeU.png) + +3) Avvia il debug; se non è abilitato, abilita il modello e autorizza l’API Key + +![alt text](https://cdn.letsmagic.cn/static/img/FsqFvaxlu7MiQB7Jg8zsgmlyBoeU.png) + +![FrLzQgYd-R0cPuh-grhOffzgNyLR.png](https://cdn.letsmagic.cn/static/img/FrLzQgYd-R0cPuh-grhOffzgNyLR.png) + +4) Dopo il successo del debug, puoi temporaneamente aggiornare il modello di embedding tramite API Magic (in futuro sarà gestito dal pannello admin) + +--- + +# 中文原文 ## 一、功能预览 > **⚠️ 提示**：管理后台正在内测中，请暂时通过[环境变量配置](../../../development/deploy/environment.md#_4-ai-%E6%A8%A1%E5%9E%8B%E9%85%8D%E7%BD%AE)来设置大模型。 diff --git a/frontend/es6-template-strings/README.md b/frontend/es6-template-strings/README.md index 060620c5a..54f95c347 100644 --- a/frontend/es6-template-strings/README.md +++ b/frontend/es6-template-strings/README.md @@ -1,5 +1,76 @@ # @dtyq/es6-template-strings +Motore di Parsing per Template Strings ES6 + +[![license][license-badge]][license-link] +![NPM Version](https://img.shields.io/npm/v/@dtyq/es6-template-strings) +[![codecov][codecov-badge]][codecov-link] + +[license-badge]: https://img.shields.io/badge/license-apache2-blue.svg +[license-link]: LICENSE +[codecov-badge]: https://codecov.io/gh/dtyq/es6-template-strings/branch/master/graph/badge.svg +[codecov-link]: https://codecov.io/gh/dtyq/es6-template-strings + +## 📋 Panoramica + +Questo pacchetto fornisce un motore di parsing per template strings che supporta la sintassi in stile ES6. Permette di interpolare variabili ed espressioni all'interno delle stringhe utilizzando la sintassi `${espressione}`. + +## 🚀 Utilizzo + +```typescript +import { resolveToString, resolveToArray } from "@dtyq/es6-template-strings"; + +// Utilizzo base +console.log(resolveToString("ciao ${nome}", { nome: "mondo" })); +// Output: "ciao mondo" + +// Restituisce array di parti del template e sostituzioni +console.log(resolveToArray("ciao ${nome}", { nome: "mondo" })); +// Output: ["ciao ", "mondo"] +``` + +## ⚙️ Opzioni di Configurazione + +| Opzione | Descrizione | Tipo | Default | Richiesto | +|:------:|:----------:|:----:|:-------:|:--------:| +| notation | Prefisso sintassi template | string | "$" | No | +| notationStart | Marcatore inizio sintassi template | string | "{" | No | +| notationEnd | Marcatore fine sintassi template | string | "}" | No | +| partial | Salta espressioni fallite invece di restituire undefined | boolean | false | No | + +## 📝 Note + +- Quando un'espressione non può essere risolta: + - Se `partial: true`, la stringa originale `${espressione}` verrà preservata + - Se `partial: false` (default), verrà restituito undefined per quell'espressione +- Il pacchetto gestisce correttamente espressioni annidate e sequenze di escape + +## 🛠️ Sviluppo + +Per configurare l'ambiente di sviluppo: + +1. Clona il repository +2. Installa le dipendenze: `npm install` +3. Costruisci il pacchetto: `npm run build` +4. Esegui i test: `npm test` + +## 🔄 Processo di Iterazione + +Il pacchetto segue il versionamento semantico: + +1. Le correzioni di bug risultano in incrementi di versione patch +2. Le nuove funzionalità che mantengono la retrocompatibilità risultano in incrementi di versione minor +3. I cambiamenti che rompono la compatibilità risultano in incrementi di versione major + +Per contribuire: +1. Fai il fork del repository +2. Crea un branch per la funzionalità +3. Invia una pull request con descrizione dettagliata delle modifiche + +--- + +# @dtyq/es6-template-strings + ES6 Template Strings Parser Engine [![license][license-badge]][license-link] diff --git a/frontend/es6-template-strings/README.zhCN.md b/frontend/es6-template-strings/README.zhCN.md index 572e10cd5..07cbcd591 100644 --- a/frontend/es6-template-strings/README.zhCN.md +++ b/frontend/es6-template-strings/README.zhCN.md @@ -1,5 +1,78 @@ # @dtyq/es6-template-strings +Motore di analisi delle stringhe template ES6 🚀 + +[![license][license-badge]][license-link] +![NPM Version](https://img.shields.io/npm/v/@dtyq/es6-template-strings) +[![codecov][codecov-badge]][codecov-link] + +[license-badge]: https://img.shields.io/badge/license-apache2-blue.svg +[license-link]: LICENSE +[codecov-badge]: https://codecov.io/gh/dtyq/es6-template-strings/branch/master/graph/badge.svg +[codecov-link]: https://codecov.io/gh/dtyq/es6-template-strings + +## Panoramica 📋 + +Questo pacchetto fornisce un motore di analisi delle stringhe template che supporta la sintassi in stile ES6. Ti permette di inserire variabili ed espressioni nelle stringhe utilizzando la sintassi `${expression}`. + +## Utilizzo 💻 + +```typescript +import { resolveToString, resolveToArray } from "@dtyq/es6-template-strings"; + +// Utilizzo base +console.log(resolveToString("hello ${name}", { name: "world" })); +// Output: "hello world" + +// Restituisce un array delle parti del template e dei valori sostituiti +console.log(resolveToArray("hello ${name}", { name: "world" })); +// Output: ["hello ", "world"] +``` + +## Opzioni di configurazione ⚙️ + +| Opzione | Descrizione | Tipo | Valore predefinito | Obbligatorio | +|:-----------------:|:-----------------------:|:------:|:------------------:|:-------------:| +| notation | Prefisso della sintassi del template | string | "$" | No | +| notationStart | Marcatore di inizio della sintassi del template | string | "{" | No | +| notationEnd | Marcatore di fine della sintassi del template | string | "}" | No | +| partial | Se saltare le espressioni che non riescono a essere analizzate | boolean | false | No | + +## Note importanti ⚠️ + +- Quando un'espressione non può essere analizzata: + - Se `partial: true`, mantiene la stringa originale `${expression}` + - Se `partial: false` (valore predefinito), l'espressione corrispondente restituisce undefined +- Il pacchetto gestisce correttamente espressioni annidate e sequenze di escape + +## Modalità di sviluppo 🛠️ + +Impostazione dell'ambiente di sviluppo: + +1. Clona il repository +2. Installa le dipendenze: `npm install` +3. Costruisci il pacchetto: `npm run build` +4. Esegui i test: `npm test` + +## Modalità di rilascio 📈 + +Il pacchetto segue le specifiche di versionamento semantico: + +1. Le correzioni di bug aumentano la versione patch +2. Le nuove funzionalità compatibili con le versioni precedenti aumentano la versione minor +3. Le modifiche breaking aumentano la versione major + +Flusso di contributi: +1. Fork del repository +2. Crea un branch per la funzionalità +3. Invia una pull request con una descrizione dettagliata delle modifiche + +--- + +## Testo originale (in cinese) 📜 + +# @dtyq/es6-template-strings + ES6 字符串模板解析引擎 [![license][license-badge]][license-link] @@ -65,4 +138,4 @@ console.log(resolveToArray("hello ${name}", { name: "world" })); 贡献流程： 1. Fork 仓库 2. 创建功能分支 -3. 提交拉取请求，详细描述更改 +3. 提交拉取请求，详细描述更改 diff --git a/frontend/magic-flow/docs/helper-lines.md b/frontend/magic-flow/docs/helper-lines.md index a49964f5c..e8b409ca6 100644 --- a/frontend/magic-flow/docs/helper-lines.md +++ b/frontend/magic-flow/docs/helper-lines.md @@ -1,3 +1,383 @@ +# Funzionalità Linee Guida di ReactFlow 🚀 + +Il componente delle linee guida di React Flow fornisce funzionalità di linee di riferimento per l'allineamento dei nodi, aiutando gli utenti a ottenere un allineamento preciso durante il trascinamento dei nodi. + +## Caratteristiche Principali 📋 + +- Visualizza linee di riferimento durante il trascinamento dei nodi +- Supporta la funzionalità di snap dei nodi per un allineamento preciso +- Supporta l'allineamento in direzione orizzontale e verticale +- Supporta vari modi di allineamento: allineamento sinistro, destro, centrato, superiore, inferiore, ecc. +- Si adatta al zoom e alla panoramica del viewport +- Fornisce opzioni di configurazione personalizzate ricche +- Supporta l'attivazione/disattivazione tramite pulsante del pannello di controllo o scorciatoie da tastiera + +## Metodo di Utilizzo 🛠️ + +### Utilizzo Base + +```tsx +import { ReactFlow, useViewport } from 'reactflow'; +import { HelperLines, useHelperLines } from '@/MagicFlow/components/HelperLines'; + +function FlowComponent() { + const { x, y, zoom } = useViewport(); + const [helperLinesEnabled, setHelperLinesEnabled] = useState(false); + + const { + horizontalLines, + verticalLines, + handleNodeDragStart, + handleNodeDrag, + handleNodeDragStop, + hasHelperLines + } = useHelperLines({ + nodes, + onNodeDragStart, + onNodeDrag, + onNodeDragStop, + onNodesChange, // Se necessario per la funzionalità di snap dei nodi, questo parametro deve essere fornito + enabled: helperLinesEnabled, // Controlla l'interruttore della funzionalità delle linee guida + }); + + return ( + <> + {/* Aggiungi un pulsante di controllo */} + + + + {/* Altri componenti */} + + {/* Renderizza le linee guida */} + {hasHelperLines && ( + + )} + + + ); +} +``` + +### Configurazione Personalizzata 🎨 + +Puoi personalizzare il comportamento e lo stile delle linee guida tramite il parametro `options`: + +```tsx +const { + horizontalLines, + verticalLines, + // ... +} = useHelperLines({ + nodes, + onNodeDragStart, + onNodeDrag, + onNodeDragStop, + onNodesChange, + enabled: helperLinesEnabled, // Controlla abilitazione/disabilitazione tramite stato + options: { + threshold: 8, // Soglia di allineamento + color: '#0077ff', // Colore delle linee guida + lineWidth: 2, // Larghezza delle linee guida + zIndex: 10000, // z-index + enableSnap: true // Se abilitare la funzionalità di snap dei nodi + } +}); +``` + +Quindi passa queste opzioni al componente `HelperLines`: + +```tsx + +``` + +## Riferimento API 📖 + +### Hook `useHelperLines` + +#### Parametri + +Il hook `useHelperLines` accetta un oggetto di configurazione con le seguenti proprietà: + +| Proprietà | Tipo | Obbligatorio | Descrizione | +| --- | --- | --- | --- | +| nodes | Node[] | Sì | Array di nodi di React Flow | +| onNodeDragStart | Function | No | Callback originale per l'inizio del trascinamento del nodo | +| onNodeDrag | Function | No | Callback originale per il trascinamento del nodo | +| onNodeDragStop | Function | No | Callback originale per la fine del trascinamento del nodo | +| onNodesChange | Function | No | Callback per le modifiche dei nodi, utilizzato per implementare la funzionalità di snap dei nodi | +| options | HelperLinesOptions | No | Opzioni di configurazione delle linee guida | +| enabled | boolean | No | Se abilitare la funzionalità delle linee guida, predefinito false | + +#### Valori di Ritorno + +| Proprietà | Tipo | Descrizione | +| --- | --- | --- | +| horizontalLines | number[] | Array delle posizioni delle linee guida orizzontali | +| verticalLines | number[] | Array delle posizioni delle linee guida verticali | +| handleNodeDragStart | Function | Funzione di gestione dell'inizio del trascinamento del nodo | +| handleNodeDrag | Function | Funzione di gestione del trascinamento del nodo | +| handleNodeDragStop | Function | Funzione di gestione della fine del trascinamento del nodo | +| hasHelperLines | boolean | Se ci sono linee guida da visualizzare | +| options | Object | Opzioni di configurazione attualmente utilizzate | +| enabled | boolean | Se la funzionalità delle linee guida è attualmente abilitata | + +### Componente `HelperLines` + +#### Proprietà + +| Proprietà | Tipo | Obbligatorio | Valore Predefinito | Descrizione | +| --- | --- | --- | --- | --- | +| horizontalLines | number[] | Sì | - | Array delle posizioni delle linee guida orizzontali | +| verticalLines | number[] | Sì | - | Array delle posizioni delle linee guida verticali | +| transform | ViewportTransform | Sì | - | Informazioni sulla trasformazione del viewport | +| color | string | No | '#ff0071' | Colore delle linee guida | +| lineWidth | number | No | 1 | Larghezza delle linee guida | +| zIndex | number | No | 9999 | z-index delle linee guida | + +### Definizioni dei Tipi + +```typescript +interface ViewportTransform { + x: number; + y: number; + zoom: number; +} + +interface HelperLinesOptions { + threshold?: number; + color?: string; + lineWidth?: number; + zIndex?: number; + enableSnap?: boolean; +} +``` + +## Integrazione nel Pannello di Controllo ⚙️ + +Puoi aggiungere un pulsante interruttore nel pannello di controllo del diagramma di flusso per controllare l'abilitazione/disabilitazione della funzionalità delle linee guida: + +```tsx +// Aggiungi il pulsante di controllo delle linee guida negli elementi di controllo del pannello +const controlItemGroups = [ + // ... altri gruppi di controllo + [ + { + icon: helperLinesEnabled ? ( + + ) : ( + + ), + callback: () => setHelperLinesEnabled(!helperLinesEnabled), + tooltips: `${helperLinesEnabled ? 'Disabilita' : 'Abilita'} Linee Guida (Ctrl+H)`, + helperLinesEnabled, + }, + ], +]; + +// Aggiungi supporto per scorciatoie da tastiera +useEffect(() => { + const handleKeyDown = (event) => { + // Ctrl+H o Command+H per alternare la funzionalità delle linee guida + if ((event.ctrlKey || event.metaKey) && event.key === 'h') { + event.preventDefault(); + setHelperLinesEnabled(!helperLinesEnabled); + } + }; + + document.addEventListener('keydown', handleKeyDown); + return () => { + document.removeEventListener('keydown', handleKeyDown); + }; +}, [helperLinesEnabled, setHelperLinesEnabled]); +``` + +## Principio di Implementazione 🧠 + +Il principio di implementazione principale della funzionalità delle linee guida: + +1. Ascolta gli eventi di trascinamento dei nodi +2. Durante il trascinamento, calcola la relazione di posizione tra il nodo attualmente trascinato e gli altri nodi +3. Quando i bordi o i centri dei nodi si avvicinano (inferiore alla soglia impostata), visualizza le linee di riferimento di allineamento +4. Utilizza elementi posizionati assolutamente per renderizzare le linee guida, calcolando la posizione corretta in base allo zoom e alla panoramica del viewport + +Principio di implementazione della funzionalità di snap dei nodi: + +1. Quando si rileva che il nodo si avvicina alla posizione di allineamento, calcola le coordinate di allineamento precise +2. Aggiorna la posizione del nodo tramite il callback `onNodesChange` per far "snap" il nodo alla posizione di allineamento +3. Tra più posizioni di allineamento possibili, priorita la linea di riferimento più vicina alla posizione attuale di trascinamento + +Principio di implementazione del controllo di abilitazione/disabilitazione: + +1. Utilizza la variabile di stato `helperLinesEnabled` per controllare l'interruttore della funzionalità delle linee guida +2. Quando la funzionalità è disabilitata, gli eventi di trascinamento vengono passati direttamente alle funzioni di gestione originali, senza calcoli delle linee guida +3. Alterna lo stato di abilitazione tramite pulsante del pannello di controllo o scorciatoia da tastiera +4. Renderizza il componente delle linee guida solo quando la funzionalità è abilitata e ci sono nodi allineati + +Le linee guida controllano i seguenti modi di allineamento: + +- Direzione orizzontale + - Allineamento superiore: il bordo superiore del nodo si allinea con il bordo superiore di altri nodi + - Allineamento inferiore: il bordo inferiore del nodo si allinea con il bordo inferiore di altri nodi + - Allineamento centrale: la linea centrale verticale del nodo si allinea con la linea centrale verticale di altri nodi + +- Direzione verticale + - Allineamento sinistro: il bordo sinistro del nodo si allinea con il bordo sinistro di altri nodi + - Allineamento destro: il bordo destro del nodo si allinea con il bordo destro di altri nodi + - Allineamento centrale: la linea centrale orizzontale del nodo si allinea con la linea centrale orizzontale di altri nodi + +## Esempio 💡 + +### Esempio Completo con Controllo Interruttore + +```tsx +import React, { useState, useCallback, useEffect } from 'react'; +import ReactFlow, { + addEdge, + Background, + Controls, + useNodesState, + useEdgesState, + useViewport +} from 'reactflow'; +import { HelperLines, useHelperLines } from '@/MagicFlow/components/HelperLines'; +import { IconRuler } from '@tabler/icons-react'; +import 'reactflow/dist/style.css'; + +const initialNodes = [ + { + id: '1', + type: 'default', + data: { label: 'Nodo 1' }, + position: { x: 250, y: 5 }, + }, + // ... altri nodi +]; + +const initialEdges = [ + // ... definizioni dei bordi +]; + +function Flow() { + const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes); + const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges); + const { x, y, zoom } = useViewport(); + const [helperLinesEnabled, setHelperLinesEnabled] = useState(false); + + const onConnect = useCallback( + (params) => setEdges((eds) => addEdge(params, eds)), + [setEdges], + ); + + // Utilizza l'hook delle linee guida + const { + horizontalLines, + verticalLines, + handleNodeDragStart, + handleNodeDrag, + handleNodeDragStop, + hasHelperLines, + } = useHelperLines({ + nodes, + onNodesChange, + enabled: helperLinesEnabled, + options: { + threshold: 8, + color: '#ff0071', + enableSnap: true + } + }); + + // Aggiungi supporto per scorciatoie da tastiera + useEffect(() => { + const handleKeyDown = (event) => { + // Ctrl+H o Command+H per alternare la funzionalità delle linee guida + if ((event.ctrlKey || event.metaKey) && event.key === 'h') { + event.preventDefault(); + setHelperLinesEnabled(!helperLinesEnabled); + } + }; + + document.addEventListener('keydown', handleKeyDown); + return () => { + document.removeEventListener('keydown', handleKeyDown); + }; + }, [helperLinesEnabled]); + + return ( +
+ {/* Pannello di controllo */} +
+ +
+ + + + + + {/* Renderizza le linee guida */} + {hasHelperLines && ( + + )} + +
+ ); +} +``` + +--- + +## Testo Originale (Cinese) 📜 + # ReactFlow 辅助线功能 React Flow 辅助线组件提供了节点对齐参考线功能，帮助用户在拖拽节点时实现精确对齐。 @@ -371,4 +751,5 @@ function Flow() { ); -} \ No newline at end of file +} +``` \ No newline at end of file diff --git a/frontend/magic-flow/docs/index.md b/frontend/magic-flow/docs/index.md index cbc334f18..d9f90130a 100644 --- a/frontend/magic-flow/docs/index.md +++ b/frontend/magic-flow/docs/index.md @@ -1,4 +1,21 @@ --- +hero: + title: Magic ✨ + description: Componenti di base del progetto Magico, inclusi componenti relativi al flusso 🔄 + actions: + - text: Componente Espressione 📊 + link: /components/magic-expression-widget + - text: Componente Modulo 📝 + link: /components/magic-json-schema-editor + - text: Componente Condizione ⚖️ + link: /components/magic-condition-edit + - text: Componente Flusso 🌊 + link: /components/magic-flow +features: +--- + + +--- hero: title: Magic description: 神奇项目的基础组件，包括流程的相关组件 diff --git a/frontend/magic-flow/src/MagicConditionEdit/index.md b/frontend/magic-flow/src/MagicConditionEdit/index.md index 41fb421e3..d806d84c8 100644 --- a/frontend/magic-flow/src/MagicConditionEdit/index.md +++ b/frontend/magic-flow/src/MagicConditionEdit/index.md @@ -1,3 +1,55 @@ +# Componente Condizione v2 🧙‍♂️ + +## Esempio Base 📝 + +```jsx +import { MagicConditionEdit } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource, mockNodeMap } from "@/MagicExpressionWidget/components/dataSource" + + +export default () => { + const [expression, setExpression] = useState(null) + + const onExpressionChange = useCallback((val) => { + console.log('value:', val) + setExpression(val) + }, []) + + return +} +``` + + +## MagicConditionEditWrap 🔄 + +```jsx +import MagicConditionEditWrap from '@/common/BaseUI/MagicConditionWrap/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource, mockNodeMap } from "@/MagicExpressionWidget/components/dataSource" + + +export default () => { + const [expression, setExpression] = useState({ + id:"xxx", + structure: undefined + }) + + const onExpressionChange = useCallback((val) => { + console.log('value:', val) + }, []) + + return +} +``` + + + + +--- + +## Testo Originale (Cinese/Inglese) 📜 + # 条件组件 v2 ## 基本的示例 @@ -31,9 +83,9 @@ import { mockDataSource, mockNodeMap } from "@/MagicExpressionWidget/components/ export default () => { const [expression, setExpression] = useState({ - id:"xxx", - structure: undefined - }) + id:"xxx", + structure: undefined + }) const onExpressionChange = useCallback((val) => { console.log('value:', val) @@ -46,4 +98,3 @@ export default () => { - diff --git a/frontend/magic-flow/src/MagicExpressionWidget/index.md b/frontend/magic-flow/src/MagicExpressionWidget/index.md index 1945b4a95..982437f80 100644 --- a/frontend/magic-flow/src/MagicExpressionWidget/index.md +++ b/frontend/magic-flow/src/MagicExpressionWidget/index.md @@ -1,3 +1,389 @@ +# Componente Espressione v2 📝 + +## Esempio Base ⚙️ + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource, mockNodeMap } from "./components/dataSource" + + +export default () => { + const [expression, setExpression] = useState(null) + + const onExpressionChange = useCallback((val) => { + // console.log('value:', val) + setExpression(val) + }, []) + + return +} +``` + +## Supporto per Sorgente Dati Funzione 🔧 + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource, mockNodeMap } from "./components/dataSource" + + +export default () => { + const [expression, setExpression] = useState(null) + + const onExpressionChange = useCallback((val) => { + // console.log('value:', val) + setExpression(val) + }, []) + + return +} +``` + +## Supporto per Modalità Textarea 📝 + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource, mockNodeMap } from "./components/dataSource" +import methodExpressionSource from "./mock/expressionSource" +import { ExpressionMode } from "./constant" + + +export default () => { + const [expression, setExpression] = useState(null) + + const onExpressionChange = useCallback((val) => { + console.log('value:', val) + setExpression(val) + }, []) + + return +} +``` + +## Supporto per Modifica Contenuto Campo Field ✏️ + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource } from "./components/dataSource" +import { ExpressionMode } from "./constant" + + +export default () => { + const [expression1, setExpression1] = useState({ + "type": "expression", + "const_value": [], + "expression_value": [ + { + "type": "fields", + "value": "token_response.body", + "name": "token响应body", + "args": [] + }, + { + "type": "input", + "value": "['code']", + "name": "", + "args": [] + } + ] + }) + const [expression2, setExpression2] = useState(null) + + const onExpression1Change = useCallback((val) => { + console.log('value1:', val) + setExpression1(val) + }, []) + + + const onExpression2Change = useCallback((val) => { + console.log('value2:', val) + setExpression2(val) + }, []) + + return <> + +
+ + +} +``` + +## Disabilitato 🚫 + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource } from "./components/dataSource" + + +export default () => { + const [expression, setExpression] = useState(null) + + const onExpressionChange = useCallback((val) => { + console.log('value:', val) + setExpression(val) + }, []) + + return +} +``` + +## Sorgente Dati Costante 📊 + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource } from "./components/dataSource" + + +export default () => { + const [expression, setExpression] = useState(null) + + const constantSource = [{ + "title": "User", + "key": "user", + "nodeId": "", + "nodeType": "21", + "type": "string", + "isRoot": false, + "children": [], + "isConstant": true + },{ + "title": "System", + "key": "system", + "nodeId": "", + "nodeType": "21", + "type": "string", + "isRoot": false, + "children": [], + "isConstant": true + }] + + const onExpressionChange = useCallback((val) => { + console.log('value:', val) + setExpression(val) + }, []) + + return +} +``` + +## Supporto per Aprire Modale di Modifica 🖼️ + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource, mockNodeMap } from "./components/dataSource" + + +export default () => { + const [expression, setExpression] = useState(null) + + const onExpressionChange = useCallback((val) => { + // console.log('value:', val) + setExpression(val) + }, []) + + return +} +``` + +## Per Adattare Diversi Campi in Tabelle Multidimensionali 📋 + +```jsx +import { MagicExpressionWidget } from '@/index'; +import React,{ useState, useCallback } from "react" +import { mockDataSource, mockNodeMap } from "./components/dataSource" +import { mockMultipleList } from "@/MagicExpressionWidget/components/nodes/LabelMultiple/mock" +import DepartmentModal from "./mock/DepartmentModal" + + +export default () => { + const [expression, setExpression] = useState(null) + + const [multiple, setMultiple] = useState(null) + + const filterMemberList = [] + + const [select, setSelect] = useState(null) + + const [datetime, setDatetime] = useState(null) + + const [checkbox, setCheckbox] = useState(null) + + const [departmentNames, setDepartmentNames] = useState(null) + + const [names, setNames] = useState(null) + + const onExpressionChange = useCallback((val) => { + console.log('value:', val) + setExpression(val) + }, []) + + const onMultipleChange = useCallback((val) => { + console.log('value:', val) + setMultiple(val) + }, []) + + const onDatetimeChange = useCallback((val) => { + console.log('value:', val) + setDatetime(val) + }, []) + + const onCheckboxChange = useCallback((val) => { + console.log('value:', val) + setCheckbox(val) + }, []) + + + const onSelectChange = useCallback((val) => { + console.log('value:', val) + setSelect(val) + }, []) + + + const onDepartmentNamesChange = useCallback((val) => { + console.log('value:', val) + setDepartmentNames(val) + }, []) + + + const onNamesChange = useCallback((val) => { + console.log('value:', val) + setNames(val) + }, []) + + const handleOk = useCallback(() => { + console.log("ok") + }, []) + + + return <> + Membri + {}, + searchType: 'member', + onSearch: async () => { + const options = await Promise.resolve(filterMemberList) + return options + } + } + }}/> + + + Selezione Singola + {} + } + }}/> + + Selezione Multipla + {} + } + }}/> + + Data + {} + } + }}/> + + + Checkbox + {} + } + }}/> + + Dipartimenti + + + + Blocco Testo Generico + {}, + editComponent: DepartmentModal, + options: [{ + id:"xxx", + label: "Base di Conoscenza di Test" + },{ + id:"yyy", + label: "Base di Conoscenza di Test 2" + }], + suffix: (item) => { + return
{ + console.log("item", item) + }}>111
+ } + } + }}/> + +} +``` + + +## Struttura Dati Sorgente Espressione 📊 + +Vedi l'esempio di espressione specifico + +| Nome Parametro | Descrizione | Tipo | Obbligatorio | +| -------------- | ----------- | ---- | ------------ | +| label | Etichetta | string | Sì | +| value | Valore Selezionato Effettivo | string | Sì | +| return_type | Tipo di Ritorno Blocco Funzione, Presente Solo se l'Opzione a Cascata è una Funzione | string | - | +| args | Parametri di Input Blocco Funzione, È un Array di Blocchi Parametri, Presente Solo se l'Opzione a Cascata è una Funzione | array | - | +| desc | Descrizione Blocco Funzione, Presente Solo se l'Opzione a Cascata è una Funzione | string | - | +| children | Opzioni Figlie Blocco Funzione, Presente Solo se l'Opzione a Cascata è una Funzione | array | - | + +## API 🔌 + +| Nome Parametro | Descrizione | Tipo | Valore Predefinito | +| -------------- | ----------- | ---- | ------------------ | +| dataSource | Sorgente Dati Espressione | DataSourceItem[](Vedi Sopra) | - | +| placeholder | Segnaposto | string | - | +| mode | Modalità Espressione | ExpressionMode | ExpressionMode.Common | +| value | Valore Espressione | InputExpressionValue | - | +| onChange | Funzione di Cambiamento Espressione | (value: InputExpressionValue) => void | () => {} | +| allowExpression| Se Consentire Espressione | boolean | false | +| pointedValueType| Specificare Tipo di Riempimento Espressione | 'const' o 'expression' | - | +| allowModifyField| Se Consentire Modifica Valore Field | false | - | +| disabled | Se Disabilitato | false | - | +| multiple | Se Selezione Multipla | true | - | + +--- + +### Testo Originale (Spostato in Fondo) 📜 + # 表达式组件 v2 ## 基本的示例 @@ -142,25 +528,25 @@ import { mockDataSource } from "./components/dataSource" export default () => { const [expression, setExpression] = useState(null) - const constantSource = [{ - "title": "User", - "key": "user", - "nodeId": "", - "nodeType": "21", - "type": "string", - "isRoot": false, - "children": [], - "isConstant": true - },{ - "title": "System", - "key": "system", - "nodeId": "", - "nodeType": "21", - "type": "string", - "isRoot": false, - "children": [], - "isConstant": true - }] + const constantSource = [{ + "title": "User", + "key": "user", + "nodeId": "", + "nodeType": "21", + "type": "string", + "isRoot": false, + "children": [], + "isConstant": true + },{ + "title": "System", + "key": "system", + "nodeId": "", + "nodeType": "21", + "type": "string", + "isRoot": false, + "children": [], + "isConstant": true + }] const onExpressionChange = useCallback((val) => { console.log('value:', val) @@ -213,7 +599,7 @@ export default () => { const [datetime, setDatetime] = useState(null) const [checkbox, setCheckbox] = useState(null) - + const [departmentNames, setDepartmentNames] = useState(null) const [names, setNames] = useState(null) @@ -227,113 +613,113 @@ export default () => { console.log('value:', val) setMultiple(val) }, []) - + const onDatetimeChange = useCallback((val) => { console.log('value:', val) setDatetime(val) }, []) - const onCheckboxChange = useCallback((val) => { + const onCheckboxChange = useCallback((val) => { console.log('value:', val) setCheckbox(val) }, []) - - const onSelectChange = useCallback((val) => { + + const onSelectChange = useCallback((val) => { console.log('value:', val) setSelect(val) }, []) - - const onDepartmentNamesChange = useCallback((val) => { + + const onDepartmentNamesChange = useCallback((val) => { console.log('value:', val) setDepartmentNames(val) }, []) - - const onNamesChange = useCallback((val) => { + + const onNamesChange = useCallback((val) => { console.log('value:', val) setNames(val) }, []) - const handleOk = useCallback(() => { - console.log("ok") + const handleOk = useCallback(() => { + console.log("ok") }, []) return <> - 成员 - {}, - searchType: 'member', - onSearch: async () => { - const options = await Promise.resolve(filterMemberList) - return options - } - } - }}/> - - - 单选 - {} - } - }}/> - - 多选 - {} - } - }}/> - - 日期 - {} - } - }}/> - - - Checkbox - {} - } - }}/> - - 部门 - - - - 通用文本块 - {}, - editComponent: DepartmentModal, - options: [{ + 成员 + {}, + searchType: 'member', + onSearch: async () => { + const options = await Promise.resolve(filterMemberList) + return options + } + } + }}/> + + + 单选 + {} + } + }}/> + + 多选 + {} + } + }}/> + + 日期 + {} + } + }}/> + + + Checkbox + {} + } + }}/> + + 部门 + + + + 通用文本块 + {}, + editComponent: DepartmentModal, + options: [{ id:"xxx", label: "测试的知识库" },{ @@ -345,9 +731,9 @@ export default () => { console.log("item", item) }}>111 } - } - }}/> - + } + }}/> + } ``` @@ -379,5 +765,3 @@ export default () => { | allowModifyField | 是否允许修改field值 | false | - | | disabled | 是否禁用 | false | - | | multiple | 是否多选 | true | - | - - diff --git a/frontend/magic-flow/src/MagicFlow/components/FlowMaterialPanel/performance-optimizations.md b/frontend/magic-flow/src/MagicFlow/components/FlowMaterialPanel/performance-optimizations.md index 87465b81d..b0505c4e9 100644 --- a/frontend/magic-flow/src/MagicFlow/components/FlowMaterialPanel/performance-optimizations.md +++ b/frontend/magic-flow/src/MagicFlow/components/FlowMaterialPanel/performance-optimizations.md @@ -1,3 +1,59 @@ +# Ottimizzazione delle Prestazioni di FlowMaterialPanel 🚀 + +Questo documento registra le ottimizzazioni delle prestazioni apportate al componente FlowMaterialPanel per risolvere i problemi di rendering lento in presenza di grandi quantità di dati. + +## Ottimizzazioni Completate ✅ + +### 1. Ottimizzazione dei Componenti Foglia (MaterialItem) 🌿 +- Utilizzo di `React.memo` per avvolgere il componente MaterialItem, aggiungendo una funzione di confronto personalizzata +- Confronto solo delle proprietà chiave (id, label, desc, ecc.), evitando rendering non necessari +- Garantire che l'aggiornamento avvenga solo quando i dati del nodo cambiano realmente + +### 2. Ottimizzazione del Componente SubGroup 📁 +- Utilizzo di `React.memo` per avvolgere il componente, aggiungendo una funzione di confronto precisa personalizzata +- Aggiunta di tracciamento dello stato di espansione/compressione, con rendering dei figli disabilitato per impostazione predefinita quando compresso +- Aggiunta del componente wrapper `SubGroupItem`, con ottimizzazione memo individuale per ciascun elemento figlio +- Memorizzazione nella cache dei dati dell'elenco dei nodi, evitando di recuperarli nuovamente ad ogni espansione +- Utilizzo di `useCallback` per avvolgere le funzioni, evitando la ricreazione ad ogni rendering + +### 3. Ottimizzazione del Componente PanelMaterial 📊 +- Utilizzo di `React.memo` per avvolgere il componente, aggiungendo una funzione di confronto personalizzata +- Utilizzo di `useCallback` per ottimizzare la funzione wrapper di MaterialItemFn +- Utilizzo di `useMemo` per ottimizzare il rendering di elenchi e gruppi, riducendo i ricalcoli non necessari +- Creazione di valori key stabili, evitando la generazione di nuove stringhe durante il re-rendering + +### 4. Aggiunta del Componente LazySubGroup per Caricamento Pigro 🐌➡️🚀 +- Utilizzo dell'API IntersectionObserver per implementare il caricamento pigro dei componenti +- Rendering del contenuto solo quando il sottocomponente entra nel viewport +- Abilitazione automatica del meccanismo di caricamento pigro per scenari con molti sottogruppi + +## Effetti delle Ottimizzazioni 📈 +Queste ottimizzazioni hanno migliorato significativamente le prestazioni di rendering del componente: +1. **Evitare il re-rendering dei componenti foglia** 🌱: Aggiornamento solo quando i dati del nodo cambiano realmente +2. **Riduzione dell'uso della memoria** 💾: Non più rendering di tutti i componenti ed elementi contemporaneamente +3. **Miglioramento della velocità di caricamento iniziale** ⚡: Ottimizzazione delle prestazioni di rendering iniziale tramite caricamento pigro +4. **Rendering su richiesta** 🔍: Solo i componenti espansi renderanno completamente il loro contenuto +5. **Riferimenti stabili** 🔒: Mantenimento di riferimenti stabili per funzioni e componenti tramite useCallback e useMemo + +## Confronto Prima e Dopo l'Ottimizzazione ⚖️ + +### Prima dell'Ottimizzazione ❌ +- Ad ogni aggiornamento del componente padre, tutti i sottocomponenti venivano re-renderizzati +- Anche quando il componente era compresso, i suoi elementi figli venivano renderizzati +- Nessun meccanismo di cache o memoizzazione, con ricreazione di funzioni e ricalcolo di proprietà ad ogni rendering + +### Dopo l'Ottimizzazione ✅ +- I componenti foglia vengono re-renderizzati solo quando i dati chiave cambiano +- I componenti in stato compresso non renderizzano i loro elementi figli, risparmiando risorse +- Tramite meccanismi di memoizzazione e cache, si riduce significativamente il carico di calcolo e rendering + +## Suggerimenti per Ulteriori Ottimizzazioni 🔮 +1. Considerare l'implementazione di un meccanismo di caricamento dati per pagine +2. Continuare a ottimizzare la complessità dei componenti, suddividendo i componenti grandi in unità funzionali più piccole +3. Aggiungere monitoraggio delle prestazioni, raccogliendo metriche reali dalle situazioni d'uso +4. Se le prestazioni rimangono problematiche, considerare l'implementazione di tecniche di time-slicing (React Concurrent Mode) + +## Testo Originale (Cinese) 📜 # FlowMaterialPanel 性能优化 本文档记录了对 FlowMaterialPanel 组件进行的性能优化，以解决在大量数据情况下的渲染卡顿问题。 @@ -51,4 +107,4 @@ 1. 考虑实现数据分页加载机制 2. 继续优化组件复杂度，拆分大组件为更小的功能组件 3. 添加性能监控，收集实际使用情况中的性能指标 -4. 如果性能仍有问题，可考虑实现时间分片技术 (React Concurrent Mode) \ No newline at end of file +4. 如果性能仍有问题，可考虑实现时间分片技术 (React Concurrent Mode) \ No newline at end of file diff --git a/frontend/magic-flow/src/MagicFlow/index.md b/frontend/magic-flow/src/MagicFlow/index.md index fdd8fa1d1..637ca040f 100644 --- a/frontend/magic-flow/src/MagicFlow/index.md +++ b/frontend/magic-flow/src/MagicFlow/index.md @@ -1,3 +1,49 @@ +# Componente di Flusso 🚀 + +## Uso Base 📖 + +```jsx +import { BaseFlow } from '@/MagicFlow/examples'; +import React,{ useState, useCallback } from "react" + + +export default () => { + return +} +``` + + + +## Apertura Modale 🪟 + +```jsx +import { BaseFlowModal } from '@/MagicFlow/examples'; +import React,{ useState, useCallback } from "react"; +import { Button } from "antd"; + + +export default () => { + + const [open, setOpen] = useState(false) + + return <> + + setOpen(false)}/> + +} +``` + +## Testo Originale # 流程组件 ## 基本使用 @@ -46,4 +92,3 @@ export default () => { } ``` - diff --git a/frontend/magic-flow/src/common/provider/BaseColorProvider/README.md b/frontend/magic-flow/src/common/provider/BaseColorProvider/README.md index 19024dad1..6a91b037e 100644 --- a/frontend/magic-flow/src/common/provider/BaseColorProvider/README.md +++ b/frontend/magic-flow/src/common/provider/BaseColorProvider/README.md @@ -1,3 +1,44 @@ +# Gestione dei Colori di Base del Progetto 🌈 + +## Distinguere scales e usages + +Gli usages sono variabili di livello business basate su scales di livello business. 🎨 + +## Tipi + +Per i dettagli, consulta il file `src/utils/palettes.ts`. 📁 + +## Come Ottenere le Variabili di Colore di Base Globali + +### Ottenere in createStyles + +```tsx +const useStyles = createStyles(({ token }) => { + return { + main: { + color: token.magicColorUsages.white, + }, + } +}) +``` + +### Ottenere tramite Hook + +```tsx +import { useBaseColor } from "@/components/providers/BaseColorProvider/hooks" + +export default function Comp() { + // ... + + const { colorScales, colorUsages } = useBaseColor() + + // ... +} +``` + +--- + +## Testo Originale (Cinese e Inglese) # 项目基础颜色管理 ## 区分 scales 和 usages diff --git a/frontend/magic-ui/components/MagicAvatar/README.md b/frontend/magic-ui/components/MagicAvatar/README.md index f0e3f52b6..b7c771bfd 100644 --- a/frontend/magic-ui/components/MagicAvatar/README.md +++ b/frontend/magic-ui/components/MagicAvatar/README.md @@ -1,3 +1,68 @@ +# MagicAvatar Componente Avatar Magico ✨ + +`MagicAvatar` è una versione migliorata del componente Avatar di Ant Design, che offre generazione automatica di colori, supporto per badge e altre funzionalità. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ----------------------------------------- | ------------------ | ------------------------------------ | +| badgeProps | BadgeProps | - | Proprietà del badge, per mostrare un badge sull'avatar | +| size | number \| 'large' \| 'small' \| 'default' | 40 | Dimensione dell'avatar | +| shape | 'circle' \| 'square' | 'square' | Forma dell'avatar, predefinita quadrata | +| src | string | - | URL dell'immagine dell'avatar | +| ...AvatarProps | - | - | Supporta tutte le proprietà di Ant Design Avatar | + +## Utilizzo Base + +```tsx +import { MagicAvatar } from '@/components/base/MagicAvatar'; + +// Utilizzo base - Usa testo (taglia automaticamente i primi due caratteri) +Nome Utente + +// Usa immagine + + +// Dimensione personalizzata +Avatar Grande +Avatar Piccolo + +// Usa badge + + Utente + + +// Stile personalizzato +Personalizzato +``` + +## Caratteristiche + +1. **Generazione Automatica Colori** 🎨: Quando non viene fornita un'immagine, genera automaticamente il colore di sfondo e testo basato sul contenuto del testo. +2. **Supporto Badge** 🏷️: Puoi aggiungere un badge sull'avatar tramite `badgeProps`, per mostrare stato o numeri. +3. **Taglio Testo** ✂️: Taglia automaticamente i primi due caratteri del testo come contenuto dell'avatar. +4. **Validazione URL** 🔗: Valida automaticamente se src è un URL valido, altrimenti torna al testo. +5. **Stile Uniforme** ✨: Fornisce bordi uniformi e ombre di testo. + +## Quando Usare + +- Quando devi mostrare un avatar utente 👤 +- Quando devi mostrare stato o numero di notifiche sull'avatar 🔔 +- Quando devi generare automaticamente un avatar colorato basato sul nome utente 🌈 +- Quando devi mostrare identificatori utente in liste o commenti 📝 + +Il componente MagicAvatar rende la presentazione degli avatar più bella e intelligente, senza bisogno di preparare immagini per ogni utente, offrendo un effetto personalizzato. 🪄 + +--- + +**Testo Originale (Cinese):** + # MagicAvatar 魔法头像组件 `MagicAvatar` 是一个基于 Ant Design Avatar 组件的增强版头像组件，提供了自动生成颜色、徽章支持等功能。 diff --git a/frontend/magic-ui/components/MagicButton/README.md b/frontend/magic-ui/components/MagicButton/README.md index af121f28c..ce1d3c3e2 100644 --- a/frontend/magic-ui/components/MagicButton/README.md +++ b/frontend/magic-ui/components/MagicButton/README.md @@ -1,3 +1,61 @@ +# MagicButton Componente Pulsante Magico ✨ + +`MagicButton` è una versione migliorata del componente Button di Ant Design, che offre più opzioni di personalizzazione e ottimizzazioni di stile. 🔘 + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------------------------------- | ------------------ | ------------------------------------ | +| justify | CSSProperties["justifyContent"] | "center" | Allineamento orizzontale del contenuto del pulsante | +| theme | boolean | true | Se applicare gli stili del tema | +| tip | ReactNode | - | Contenuto del suggerimento mostrato al passaggio del mouse | +| ...ButtonProps | - | - | Supporta tutte le proprietà del Button di Ant Design | + +## Uso Base + +```tsx +import { MagicButton } from '@/components/base/MagicButton'; + +// Pulsante base +Cliccami + +// Pulsante con icona +}>Preferiti + +// Pulsante con suggerimento +Passa il mouse per vedere il suggerimento + +// Allineamento personalizzato +Contenuto allineato a sinistra + +// Senza stili del tema +Senza stili del tema + +// Diversi tipi di pulsante +Pulsante Principale +Pulsante Predefinito +Pulsante Tratteggiato +Pulsante Link +Pulsante Testo +``` + +## Caratteristiche + +1. **Controllo Stile Migliorato** 🎨: Offre più opzioni di personalizzazione dello stile, come l'allineamento del contenuto +2. **Funzione Suggerimento Integrata** 💡: Tramite la proprietà `tip` puoi facilmente aggiungere suggerimenti al passaggio del mouse +3. **Integrazione Tema** 🌟: Puoi controllare se applicare gli stili del tema tramite la proprietà `theme` +4. **Supporto Icone Flessibile** 🖼️: Completamente compatibile con il sistema di icone di Ant Design + +## Quando Usare + +- Quando devi posizionare un pulsante sulla pagina 📍 +- Quando hai bisogno di un migliore controllo dello stile del pulsante 🎛️ +- Quando il pulsante deve avere un suggerimento al passaggio del mouse 🖱️ +- Quando il contenuto del pulsante deve avere un allineamento specifico 📐 + +Il componente MagicButton rende i tuoi pulsanti più flessibili e belli, mantenendo tutte le funzionalità del pulsante Ant Design. ✨🔘 + +## Testo Originale # MagicButton 魔法按钮组件 `MagicButton` 是一个基于 Ant Design Button 组件的增强版按钮，提供了更多的自定义选项和样式优化。 diff --git a/frontend/magic-ui/components/MagicCheckFavor/README.md b/frontend/magic-ui/components/MagicCheckFavor/README.md index c019cc7cc..903183a29 100644 --- a/frontend/magic-ui/components/MagicCheckFavor/README.md +++ b/frontend/magic-ui/components/MagicCheckFavor/README.md @@ -1,3 +1,62 @@ +# MagicCheckFavor Componente Checkbox Magico ✨ + +MagicCheckFavor è un componente checkbox con stile personalizzato, progettato appositamente per scenari come preferiti e impostazioni di preferenze. Questo componente offre un elemento interattivo selezionabile/non selezionabile, con uno stile visivo speciale che lo rende più intuitivo nelle funzionalità relative ai preferiti. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | -------------------------- | ------------------ | ------------------------------- | +| checked | boolean | false | Se è selezionato | +| onChange | (checked: boolean) => void | - | Funzione di callback quando lo stato selezionato cambia | + +## Uso Base + +```tsx +import MagicCheckFavor from '@/components/base/MagicCheckFavor'; +import { useState } from 'react'; + +// Uso base +const [isChecked, setIsChecked] = useState(false); + + setIsChecked(checked)} +/> + +// Selezionato per default + console.log('Stato selezionato:', checked)} +/> + +// Uso in un elemento di lista +
+ Progetto preferito + handleFavoriteChange(item.id, checked)} + /> +
+``` + +## Caratteristiche + +- **Stile Personalizzato** 🎨: Diverso dai checkbox tradizionali, offre un aspetto più adatto a scenari di preferiti +- **Semplice da Usare** 👍: API progettata in modo semplice e facile da utilizzare +- **Gestione Stato** 🔄: Supporta modalità controllata, permettendo di controllare lo stato selezionato tramite stato esterno +- **Feedback Interattivo** ✨: Fornisce feedback visivo intuitivo, migliorando l'esperienza utente +- **Leggero** 🪶: Implementazione del componente semplice, senza dipendenze aggiuntive + +## Scenari d'Uso + +- Selezione di elementi in una lista di preferiti +- Elemento interattivo per funzionalità di "Mi piace"/"Preferito" +- Opzioni a interruttore nelle impostazioni di preferenze +- Qualsiasi elemento dell'interfaccia che necessita di rappresentare uno stato di "preferito" o "apprezzato" + +Il componente MagicCheckFavor, fornendo un checkbox visivamente più adatto a scenari di preferiti, permette agli utenti di ottenere un feedback più intuitivo durante le operazioni di preferenza, elevando l'esperienza utente complessiva. 🌟 + +## Testo Originale # MagicCheckFavor 魔法复选组件 MagicCheckFavor 是一个自定义样式的复选框组件，专为收藏夹和偏好设置等场景设计。该组件提供了一个可选中/取消选中的交互元素，具有特殊的视觉样式，使其在收藏相关功能中更加直观。 diff --git a/frontend/magic-ui/components/MagicCollapse/README.md b/frontend/magic-ui/components/MagicCollapse/README.md index 317c01070..ad47109f9 100644 --- a/frontend/magic-ui/components/MagicCollapse/README.md +++ b/frontend/magic-ui/components/MagicCollapse/README.md @@ -1,3 +1,85 @@ +# MagicCollapse 🪄 Componente Pannello a Fisarmonica Magico + +`MagicCollapse` è una versione migliorata del componente Collapse di Ant Design, che offre stili più belli e una migliore esperienza utente. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ---------------- | ---- | ------------------ | ------------------------------------ | +| ...CollapseProps | - | - | Supporta tutte le proprietà di Ant Design Collapse | + +## Uso Base + +```tsx +import { MagicCollapse } from '@/components/base/MagicCollapse'; +import { Collapse } from 'antd'; + +const { Panel } = Collapse; + +// Uso base + + +

Questo è il contenuto del pannello 1

+ + +

Questo è il contenuto del pannello 2

+ + +

Questo è il contenuto del pannello 3

+ + + +// Espandi pannelli specifici per default + + +

Questo è il contenuto del pannello espanso per default

+ + +

Questo è il contenuto del pannello chiuso per default

+ + + +// Modalità fisarmonica (solo un pannello espanso alla volta) + + +

Contenuto pannello fisarmonica 1

+ + +

Contenuto pannello fisarmonica 2

+ + + +// Ascolta eventi di espansione/collasso + console.log('Pannello attualmente espanso:', key)}> + +

Contenuto pannello 1

+ + +

Contenuto pannello 2

+ + +``` + +## Caratteristiche ✨ + +1. **Stili Ottimizzati** 🎨: Usa la modalità ghost, rimuove i bordi per un aspetto più pulito e bello +2. **Icona di Espansione Personalizzata** 🔄: Usa il componente MagicIcon come icona di espansione per un effetto visivo più uniforme +3. **Animazione Fluida** 🌊: Effetto di rotazione fluida durante espansione/collasso +4. **Layout Flessibile** 📐: Icona di espansione sul lato destro, seguendo le tendenze di design moderne + +## Quando Usare ❓ + +- Quando devi raggruppare contenuti complessi per la visualizzazione +- Quando devi risparmiare spazio sulla pagina, collassando i contenuti +- Quando devi creare un effetto fisarmonica (solo un pannello espanso alla volta) +- Quando devi mostrare informazioni categorizzate, permettendo all'utente di visualizzarle su richiesta + +Il componente MagicCollapse rende i tuoi pannelli a fisarmonica più belli e user-friendly, mantenendo tutte le funzionalità di Ant Design Collapse. + +--- + +## Testo Originale (Inglese) 📜 + # MagicCollapse 魔法折叠面板组件 `MagicCollapse` 是一个基于 Ant Design Collapse 组件的增强版折叠面板，提供了更美观的样式和更好的用户体验。 diff --git a/frontend/magic-ui/components/MagicDropdown/README.md b/frontend/magic-ui/components/MagicDropdown/README.md index 536a420ae..1b46f92d5 100644 --- a/frontend/magic-ui/components/MagicDropdown/README.md +++ b/frontend/magic-ui/components/MagicDropdown/README.md @@ -1,3 +1,96 @@ +# MagicDropdown Componente Menu a Discesa Magico 🌟 + +`MagicDropdown` è una versione migliorata del componente Dropdown di Ant Design, che offre stili più belli e una migliore esperienza utente. ✨ + +## Proprietà 📋 + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ----------------- | --------- | ------------------ | --------------------------------------------- | +| menu | MenuProps | - | Configurazione del menu, per definire il contenuto e il comportamento del menu a discesa | +| overlayClassName | string | - | Nome classe personalizzata per il menu a discesa | +| ...DropDownProps | - | - | Supporta tutte le proprietà del Dropdown di Ant Design | + +## Uso Base 🔧 + +```tsx +import { MagicDropdown } from '@/components/base/MagicDropdown'; +import { Button, Space } from 'antd'; +import type { MenuProps } from 'antd'; +import { IconSettings, IconUser, IconLogout } from '@tabler/icons-react'; + +// Definire gli elementi del menu +const items: MenuProps['items'] = [ + { + key: '1', + label: 'Informazioni Personali', + icon: , + }, + { + key: '2', + label: 'Impostazioni', + icon: , + }, + { + type: 'divider', + }, + { + key: '3', + label: 'Esci dal Login', + icon: , + danger: true, + }, +]; + +// Uso base + + + + +// Con modalità di attivazione + + + + +// Con freccia + + + + +// Con gestione eventi + console.log('Cliccato elemento menu:', e.key), + }} +> + + + +// Stato disabilitato + + + +``` + +## Caratteristiche 🌟 + +1. **Stili Ottimizzati** 🎨: Angoli più arrotondati, spaziatura più ragionevole e effetti hover più belli +2. **Ottimizzazione Spaziatura Icone** 📐: Ottimizzata la spaziatura tra icone e testo per un layout più armonioso +3. **Miglioramento Stili Elementi Pericolosi** ⚠️: Forniti segnali visivi più evidenti per operazioni pericolose +4. **Ottimizzazione Posizione Sottomenu** 📍: Regolata la posizione dei sottomenu per un display più naturale +5. **Adattamento Tema** 🌙: Adatta automaticamente temi chiari/scuri, fornendo un'esperienza visiva coerente + +## Quando Usare ❓ + +- Quando hai bisogno di posizionare un menu a discesa sulla pagina 📄 +- Quando vuoi fornire all'utente molteplici opzioni operative senza occupare troppo spazio 📦 +- Quando hai bisogno di mostrare operazioni correlate in gruppi 👥 +- Quando hai bisogno di includere operazioni pericolose nel menu a discesa 🚨 +- Quando desideri stili di menu a discesa più belli ✨ + +Il componente MagicDropdown rende i tuoi menu a discesa più belli e facili da usare, mantenendo tutte le funzionalità del Dropdown di Ant Design. 🚀 + +## Testo Originale (Inglese e Cinese) # MagicDropdown 魔法下拉菜单组件 `MagicDropdown` 是一个基于 Ant Design Dropdown 组件的增强版下拉菜单，提供了更美观的样式和更好的用户体验。 diff --git a/frontend/magic-ui/components/MagicEllipseWithTooltip/README.md b/frontend/magic-ui/components/MagicEllipseWithTooltip/README.md index 89b8f3329..7f65f3b40 100644 --- a/frontend/magic-ui/components/MagicEllipseWithTooltip/README.md +++ b/frontend/magic-ui/components/MagicEllipseWithTooltip/README.md @@ -1,3 +1,96 @@ +# MagicEllipseWithTooltip Componente di Ellissi Magica con Tooltip 📝 + +`MagicEllipseWithTooltip` è un componente intelligente per l'ellissi del testo, che mostra automaticamente i puntini di sospensione quando il testo supera la larghezza specificata e visualizza il testo completo tramite un tooltip al passaggio del mouse. + +## Proprietà 🔧 + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ------------------ | ------ | ------------------ | --------------------------------------------------------- | +| text | string | - | Il contenuto del testo da visualizzare | +| maxWidth | string | - | Larghezza massima del testo, con ellissi per il resto, es. "200px", "50%" | +| ...HTMLAttributes | - | - | Supporta tutti gli attributi dell'elemento HTML div | + +## Uso Base 🚀 + +```tsx +import { MagicEllipseWithTooltip } from '@/components/base/MagicEllipseWithTooltip'; + +// Uso base + + +// Stile personalizzato + + +// Uso in una cella di tabella + ( + + ), + }, + // Altre colonne... + ]} + dataSource={data} +/> + +// Uso in un elemento di lista + ( + + + + )} +/> + +// Gestione eventi + console.log('Il testo è stato cliccato')} +/> +``` + +## Caratteristiche ✨ + +1. **Rilevamento Intelligente** 🔍: Mostra il tooltip solo quando il testo supera effettivamente lo spazio +2. **Design Semplice** 🎨: Usa ellissi su una sola riga per mantenere l'interfaccia pulita +3. **Configurazione Flessibile** ⚙️: Puoi impostare la larghezza massima per adattarsi a vari layout +4. **Completamente Personalizzabile** 🛠️: Supporta tutti gli attributi e stili dell'elemento div + +## Quando Usare 📋 + +- Quando devi mostrare testi potenzialmente lunghi in spazi limitati +- Quando vuoi mantenere l'interfaccia pulita senza perdere informazioni +- In tabelle, liste, carte e altri componenti per mostrare titoli o descrizioni +- Quando vuoi assicurarti che gli utenti possano vedere il contenuto completo del testo troncato + +Il componente MagicEllipseWithTooltip rende la presentazione di testi lunghi più elegante e user-friendly, mantenendo l'interfaccia pulita e garantendo l'integrità delle informazioni. 🌟 + +--- + +## Testo Originale (Cinese e Inglese) 📜 + # MagicEllipseWithTooltip 魔法省略提示组件 `MagicEllipseWithTooltip` 是一个智能的文本省略组件，当文本超出指定宽度时自动显示省略号，并在鼠标悬停时通过工具提示显示完整文本。 diff --git a/frontend/magic-ui/components/MagicIcon/README.md b/frontend/magic-ui/components/MagicIcon/README.md index 095e49d44..e6201c1bf 100644 --- a/frontend/magic-ui/components/MagicIcon/README.md +++ b/frontend/magic-ui/components/MagicIcon/README.md @@ -1,3 +1,61 @@ +# MagicIcon Componente Icona Magica ✨ + +`MagicIcon` è un componente wrapper per icone basato su Tabler Icons, che fornisce adattamento al tema e controllo uniforme degli stili. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ----------------------------------------------------------------------- | ------------------ | ------------------------------- | +| component | ForwardRefExoticComponent & RefAttributes> | - | Il componente icona Tabler da renderizzare | +| active | boolean | false | Se è in stato attivo | +| animation | boolean | false | Se abilitare effetti di animazione | +| ...IconProps | - | - | Supporta tutte le proprietà di Tabler Icons | + +## Utilizzo Base + +```tsx +import { MagicIcon } from '@/components/base/MagicIcon'; +import { IconHome, IconStar, IconSettings } from '@tabler/icons-react'; + +// Icona base + + +// Dimensione personalizzata + + +// Colore personalizzato (sovrascrive il colore del tema) + + +// Spessore linea personalizzato + + +// Stato attivo + + +// Con effetto animazione (se implementato) + +``` + +## Caratteristiche 🌟 + +1. **Adattamento al Tema** 🎨: Regola automaticamente il colore dell'icona in base al tema corrente (chiaro/scuro) +2. **Stile Uniforme** 📏: Fornisce spessore linea e colore uniformi per default +3. **Sicurezza dei Tipi** 🔒: Supporto completo per TypeScript con definizioni di tipo complete +4. **Estensione Flessibile** 🔧: Facilita la personalizzazione delle caratteristiche dell'icona tramite proprietà + +## Quando Usare ❓ + +- Quando hai bisogno di usare icone Tabler nella tua app +- Quando le icone devono adattarsi automaticamente ai cambiamenti di tema +- Quando devi gestire uniformemente gli stili delle icone +- Quando devi aggiungere stati interattivi alle icone (come stato attivo) + +Il componente MagicIcon rende l'uso delle icone più semplice e uniforme, assicurando che si adattino alle impostazioni del tema della tua app. 🚀 + +--- + +**Testo Originale (Cinese):** + # MagicIcon 魔法图标组件 `MagicIcon` 是一个基于 Tabler Icons 的图标包装组件，提供了主题适配和统一的样式控制。 diff --git a/frontend/magic-ui/components/MagicMenu/README.md b/frontend/magic-ui/components/MagicMenu/README.md index fdc8271cd..e1d60a51c 100644 --- a/frontend/magic-ui/components/MagicMenu/README.md +++ b/frontend/magic-ui/components/MagicMenu/README.md @@ -1,3 +1,143 @@ +# MagicMenu Componente Menu Magico 🪄 + +`MagicMenu` è una versione migliorata del componente Menu di Ant Design, che offre uno stile più pulito e una migliore esperienza utente. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---- | ------------------ | ------------------------------------ | +| ...MenuProps | - | - | Supporta tutte le proprietà del Menu di Ant Design | + +## Uso Base + +```tsx +import { MagicMenu } from '@/components/base/MagicMenu'; +import { IconHome, IconUser, IconSettings } from '@tabler/icons-react'; + +// Uso base +, + }, + { + key: 'profile', + label: 'Centro Personale', + icon: , + }, + { + key: 'settings', + label: 'Impostazioni', + icon: , + }, + ]} +/> + +// Elemento selezionato predefinito + + +// Menu verticale + + +// Con sottomenu + + +// Operazione pericolosa + + +// Ascolta evento di selezione + console.log('Cliccato:', key)} + items={[ + { + key: 'home', + label: 'Homepage', + }, + { + key: 'profile', + label: 'Centro Personale', + }, + ]} +/> +``` + +## Caratteristiche ✨ + +1. **Design Pulito** 🧹: Rimuove il colore di sfondo e il bordo degli elementi selezionati, per un effetto visivo più pulito +2. **Sfondo Trasparente** 🔍: Sfondo del menu trasparente, per integrarsi meglio in varie interfacce +3. **Spaziatura Ottimizzata** 📏: Spaziatura ragionevole tra gli elementi del menu, per migliorare la leggibilità +4. **Ottimizzazione Operazioni Pericolose** ⚠️: Gli elementi di operazioni pericolose hanno un effetto hover speciale, per renderli più evidenti + +## Quando Usare 🕒 + +- Quando hai bisogno di fornire funzionalità di navigazione nella pagina +- Quando devi mostrare un gruppo di operazioni o funzionalità correlate +- Quando devi mostrare opzioni in un menu a discesa +- Quando devi creare un menu contestuale (menu destro) + +Il componente MagicMenu rende i tuoi menu più puliti e user-friendly, mantenendo tutte le funzionalità del Menu di Ant Design. + +## Testo Originale # MagicMenu 魔法菜单组件 `MagicMenu` 是一个基于 Ant Design Menu 组件的增强版菜单，提供了更简洁的样式和更好的用户体验。 diff --git a/frontend/magic-ui/components/MagicModal/README.md b/frontend/magic-ui/components/MagicModal/README.md index 7e83af4ac..d184275d0 100644 --- a/frontend/magic-ui/components/MagicModal/README.md +++ b/frontend/magic-ui/components/MagicModal/README.md @@ -1,3 +1,114 @@ +# MagicModal 🪄 Componente Modale Magico + +`MagicModal` è una versione migliorata del componente Modal di Ant Design, che offre stili più belli e supporto per l'internazionalizzazione. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---- | ------------------ | ------------------------------------ | +| ...ModalProps | - | - | Supporta tutte le proprietà del Modal di Ant Design | + +## Metodi Statici + +MagicModal fornisce gli stessi metodi statici del Modal di Ant Design, ma con supporto per l'internazionalizzazione e ottimizzazioni di stile: + +- `MagicModal.confirm(config)` - Dialogo di conferma ✅ +- `MagicModal.info(config)` - Dialogo informativo ℹ️ +- `MagicModal.success(config)` - Dialogo di successo 🎉 +- `MagicModal.error(config)` - Dialogo di errore ❌ +- `MagicModal.warning(config)` - Dialogo di avviso ⚠️ + +## Uso Base + +```tsx +import { MagicModal } from "@/components/base/MagicModal" +import { useState } from "react" + +// Dialogo base +const MyComponent = () => { + const [isModalOpen, setIsModalOpen] = useState(false) + + return ( + <> + + setIsModalOpen(false)} + onCancel={() => setIsModalOpen(false)} + > +

Questo è il contenuto del dialogo

+ + + ) +} + +// Usando metodi statici +const showConfirm = () => { + MagicModal.confirm({ + title: "Conferma Operazione", + content: "Sei sicuro di voler eseguire questa operazione?", + onOk() { + console.log("L'utente ha cliccato conferma") + }, + onCancel() { + console.log("L'utente ha cliccato annulla") + }, + }) +} + +// Suggerimento informativo +const showInfo = () => { + MagicModal.info({ + title: "Suggerimento Informativo", + content: "Questa è un'informazione importante", + }) +} + +// Suggerimento di successo +const showSuccess = () => { + MagicModal.success({ + title: "Operazione Riuscita", + content: "I dati sono stati salvati con successo", + }) +} + +// Suggerimento di errore +const showError = () => { + MagicModal.error({ + title: "Operazione Fallita", + content: "Errore durante il salvataggio dei dati", + }) +} + +// Suggerimento di avviso +const showWarning = () => { + MagicModal.warning({ + title: "Avviso", + content: "Questa operazione potrebbe causare perdita di dati", + }) +} +``` + +## Caratteristiche + +1. **Stili Ottimizzati** 🎨: Testata, area contenuto e piè di pagina hanno ottimizzazioni di stile specifiche +2. **Icone Personalizzate** 🖼️: Fornisce icone personalizzate per dialoghi di tipo info, ecc. +3. **Ottimizzazioni Stile Pulsanti** 🔘: I pulsanti del dialogo hanno stili e esperienze interattive migliori + +## Quando Usare + +- Quando hai bisogno che l'utente gestisca transazioni senza interrompere il flusso di lavoro con un reindirizzamento pagina 📄 +- Quando devi mostrare suggerimenti di sistema 💬 +- Quando devi mostrare feedback in forma di dialogo 📢 +- Quando devi eseguire conferme utente ✅ + +Il componente MagicModal rende i tuoi dialoghi più belli e user-friendly, fornendo al contempo supporto completo per l'internazionalizzazione. + +--- + +## Testo Originale (Cinese e Inglese) + # MagicModal 魔法对话框组件 `MagicModal` 是一个基于 Ant Design Modal 组件的增强版对话框，提供了更美观的样式和国际化支持。 diff --git a/frontend/magic-ui/components/MagicPageContainer/README.md b/frontend/magic-ui/components/MagicPageContainer/README.md index 62aa5bbf8..256340b36 100644 --- a/frontend/magic-ui/components/MagicPageContainer/README.md +++ b/frontend/magic-ui/components/MagicPageContainer/README.md @@ -1,3 +1,94 @@ +# PageContainer 📄 Componente Contenitore Pagina + +`PageContainer` è un componente contenitore utilizzato per avvolgere il contenuto della pagina, fornendo un layout di pagina unificato, una barra del titolo e funzionalità di chiusura. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---------- | ------------------ | ------------------------------------ | +| icon | ReactNode | - | Icona prima del titolo della pagina | +| closeable | boolean | false | Se mostrare il pulsante di chiusura | +| onClose | () => void | - | Funzione di callback per il clic sul pulsante di chiusura | +| className | string | - | Nome classe personalizzato del contenitore | +| ...CardProps | - | - | Supporta tutte le proprietà di Ant Design Card | + +## Utilizzo Base + +```tsx +import { PageContainer } from '@/components/base/PageContainer'; +import { IconHome } from '@tabler/icons-react'; + +// Utilizzo base + +
Contenuto Pagina
+ + +// Pagina con icona +} +> +
Contenuto Home
+ + +// Pagina chiudibile + console.log('Pagina chiusa')} +> +
Contenuto Pagina Dettagli
+ + +// Stile intestazione personalizzato + +
Contenuto Pagina
+ + +// Utilizzo in layout + + Barra Laterale + + +
Contenuto Principale
+ + + + +// Utilizzo annidato + +
+ +
Contenuto Interno
+ +
+ +``` + +## Caratteristiche ✨ + +1. **Layout Unificato** 📐: Fornisce una struttura di layout di pagina unificata +2. **Design Responsivo** 📱: Si adatta automaticamente a diverse dimensioni dello schermo +3. **Adattamento Tema** 🌙: Si adatta automaticamente a temi chiari/scuri +4. **Barra Titolo Fissa** 📌: La barra del titolo rimane fissa in alto durante lo scorrimento +5. **Funzionalità Chiusura** ❌: Può aggiungere un pulsante di chiusura per la navigazione in app multipagina + +## Quando Usare + +- Quando è necessario fornire una struttura di layout unificata per la pagina +- Quando la pagina necessita di una barra del titolo e funzionalità di chiusura +- Quando si creano più pagine con aspetto coerente nell'app +- Quando la barra del titolo della pagina deve rimanere visibile durante lo scorrimento +- Quando è necessario mostrare icone e titoli nella pagina + +Il componente PageContainer rende il layout della tua pagina più unificato e professionale, adatto a vari scenari che richiedono pagine strutturate. + +--- + +## Testo Originale (Cinese/Inglese) # PageContainer 页面容器组件 `PageContainer` 是一个用于包裹页面内容的容器组件，提供了统一的页面布局、标题栏和关闭功能。 diff --git a/frontend/magic-ui/components/MagicSearch/README.md b/frontend/magic-ui/components/MagicSearch/README.md index 605a393b2..1c4fa8bdc 100644 --- a/frontend/magic-ui/components/MagicSearch/README.md +++ b/frontend/magic-ui/components/MagicSearch/README.md @@ -1,3 +1,65 @@ +# MagicSearch 🔍 Componente di Ricerca Magica + +`MagicSearch` è una versione semplificata del componente Input di Ant Design, che fornisce un'icona di ricerca integrata e stili ottimizzati. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---- | ------------------ | ------------------------------------ | +| ...InputProps | - | - | Supporta tutte le proprietà di Input di Ant Design | + +## Utilizzo Base + +```tsx +import { MagicSearch } from '@/components/base/MagicSearch'; + +// Utilizzo base + + +// Con valore predefinito + + +// Ascolta cambiamenti di input + console.log('Input corrente:', e.target.value)} +/> + +// Segnaposto personalizzato + + +// Stato disabilitato + + +// Stile personalizzato + + +// Utilizzo con riferimento +const searchRef = useRef(null); + +``` + +## Caratteristiche + +1. **Icona di ricerca integrata** 🔍: Mostra per default un'icona di ricerca davanti all'input +2. **Supporto internazionalizzazione** 🌍: Utilizza automaticamente la traduzione i18n di "Ricerca" come segnaposto predefinito +3. **Design semplice** ✨: Fornisce uno stile semplice per l'input di ricerca +4. **Completamente personalizzabile** 🎨: Supporta tutte le proprietà del componente Input di Ant Design + +## Quando Utilizzare + +- Quando hai bisogno di aggiungere un semplice input di ricerca alla pagina +- Quando non hai bisogno di un pulsante di ricerca, solo dell'input e dell'icona di ricerca +- Quando hai bisogno di un componente di ricerca leggero +- Quando hai bisogno di utilizzarlo con altri componenti per ricerche + +Il componente MagicSearch rende il tuo input di ricerca più semplice e facile da usare, adatto a vari scenari che richiedono funzionalità di ricerca. 🚀 + +--- + +**Testo Originale (Inglese):** + # MagicSearch 魔法搜索组件 `MagicSearch` 是一个基于 Ant Design Input 组件的简化版搜索输入框，提供了内置搜索图标和优化的样式。 diff --git a/frontend/magic-ui/components/MagicSegmented/README.md b/frontend/magic-ui/components/MagicSegmented/README.md index 22634cc70..6222d9a30 100644 --- a/frontend/magic-ui/components/MagicSegmented/README.md +++ b/frontend/magic-ui/components/MagicSegmented/README.md @@ -1,3 +1,145 @@ +# Componente MagicSegmented 🎨 + +Il componente MagicSegmented è un controller segmentato migliorato basato su Ant Design Segmented, che offre stili e effetti interattivi più belli. ✨ + +## Caratteristiche Funzionali 🚀 + +- **Design Arrotondato** 🔄: Fornisce di default uno stile con angoli arrotondati, più moderno e accattivante +- **Stili Personalizzati** 🌙: Adattato alla modalità scura, per un'esperienza visiva unificata +- **Facilità d'Uso** 🛠️: Mantiene la stessa API di Ant Design Segmented +- **Compatibilità Completa** ✅: Supporta tutte le proprietà e funzionalità di Ant Design Segmented + +## Installazione 📦 + +```bash +# Già incluso in @dtyq/magic-ui, non richiede installazione separata +``` + +## Uso Base 📖 + +```tsx +import { MagicSegmented } from "@dtyq/magic-ui" + +const App = () => { + return +} +``` + +## Gestione dei Cambiamenti di Opzione 🔄 + +```tsx +import { MagicSegmented } from "@dtyq/magic-ui" +import { useState } from "react" + +const App = () => { + const [value, setValue] = useState("Giornaliero") + + const handleChange = (newValue) => { + setValue(newValue) + console.log("Selezionato corrente:", newValue) + } + + return ( + + ) +} +``` + +## Opzioni di Tipo Oggetto 📋 + +```tsx +import { MagicSegmented } from "@dtyq/magic-ui" + +const App = () => { + return ( + + ) +} +``` + +## Opzioni con Icone 🖼️ + +```tsx +import { MagicSegmented } from "@dtyq/magic-ui" +import { AppstoreOutlined, BarsOutlined } from "@ant-design/icons" + +const App = () => { + return ( + , + label: "Lista", + }, + { + value: "grid", + icon: , + label: "Griglia", + }, + ]} + /> + ) +} +``` + +## Design Non Arrotondato 🔲 + +```tsx +import { MagicSegmented } from "@dtyq/magic-ui" + +const App = () => { + return +} +``` + +## Stato Disabilitato 🚫 + +```tsx +import { MagicSegmented } from "@dtyq/magic-ui" + +const App = () => { + return +} +``` + +## Descrizione delle Proprietà 📋 + +Il componente MagicSegmented eredita tutte le proprietà del componente Ant Design Segmented e aggiunge le seguenti proprietà: + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------- | ------------------ | ------------------- | +| circle | boolean | true | Se usare il design arrotondato | + +Proprietà principali ereditate: + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ | ---------------------------- | +| options | string[] \| number[] \| Array<{ label: ReactNode; value: string \| number; icon?: ReactNode; disabled?: boolean }> | [] | Configura ogni Segmented Item | +| defaultValue | string \| number | - | Valore selezionato di default | +| value | string \| number | - | Valore attualmente selezionato | +| onChange | (value: string \| number) => void | - | Funzione di callback per i cambiamenti di opzione | +| disabled | boolean | false | Se disabilitare | +| block | boolean | false | Regola la larghezza alla larghezza dell'elemento padre | +| size | 'large' \| 'middle' \| 'small' | 'middle' | Dimensione del controllo | + +Per più proprietà, consulta la [documentazione di Ant Design Segmented](https://ant.design/components/segmented-cn/). + +## Note Importanti ⚠️ + +1. MagicSegmented usa di default il design arrotondato, può essere impostato a angoli squadrati tramite la proprietà `circle` +2. Questo componente ha ottimizzazioni di stile speciali in modalità scura, senza bisogno di configurazioni aggiuntive +3. Quando necessario combinare con altri componenti, si raccomanda di usare opzioni di tipo oggetto per una gestione più facile dello stato + +## Testo Originale (Cinese) 📜 + # MagicSegmented 组件 MagicSegmented 是一个基于 Ant Design Segmented 的增强分段控制器组件，提供了更美观的样式和交互效果。 diff --git a/frontend/magic-ui/components/MagicSpin/README.md b/frontend/magic-ui/components/MagicSpin/README.md index 88cab0e9f..bdbf22c75 100644 --- a/frontend/magic-ui/components/MagicSpin/README.md +++ b/frontend/magic-ui/components/MagicSpin/README.md @@ -1,3 +1,66 @@ +# MagicSpin Componente di Caricamento Magico ⏳ + +`MagicSpin` è una versione migliorata del componente Spin di Ant Design, che offre animazioni di caricamento brandizzate e un migliore controllo degli stili. 🔄 + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------- | ------------------ | ------------------------------------ | +| section | boolean | false | Se utilizzare l'animazione di caricamento segmentata | +| ...SpinProps | - | - | Supporta tutte le proprietà di Ant Design Spin | + +## Uso Base + +```tsx +import { MagicSpin } from '@/components/base/MagicSpin'; + +// Uso base + + +// Avvolgere contenuto + +
Contenuto in caricamento
+ + +// Dimensioni diverse + + {/* Dimensione predefinita */} + + +// Animazione di caricamento segmentata + + +// Centrare in un contenitore +
+ +
+ +// Con testo di suggerimento + +``` + +## Caratteristiche ✨ + +1. **Animazione Brandizzata**: Utilizza l'animazione Lottie del brand Magic come indicatore di caricamento 🎨 +2. **Dimensioni Adattive**: Fornisce tre dimensioni preimpostate: piccola, media e grande 📏 +3. **Layout Centrato**: Si centra automaticamente nel contenitore 🔍 +4. **Animazione Segmentata**: Puoi alternare stili di animazione diversi tramite la proprietà `section` 🎭 +5. **Adattamento Tema**: Si adatta automaticamente ai temi chiaro/scuro 🌙 + +## Quando Usare + +- Quando carichi una pagina o un componente per mostrare lo stato di caricamento 📄 +- Durante richieste di dati per fornire feedback visivo 📊 +- Per operazioni di lunga durata per fornire un suggerimento di attesa ⏱️ +- Quando è necessario impedire all'utente di interagire con il contenuto in caricamento 🚫 +- Quando è necessaria un'esperienza di caricamento brandizzata 🏷️ + +Il componente MagicSpin rende la visualizzazione dello stato di caricamento più bella e brandizzata, adatto per vari scenari che richiedono suggerimenti di caricamento. 👍 + +--- + +**Testo Originale (Cinese e Inglese):** + # MagicSpin 魔法加载组件 `MagicSpin` 是一个基于 Ant Design Spin 组件的增强版加载组件，提供了品牌化的加载动画和更好的样式控制。 diff --git a/frontend/magic-ui/components/MagicSplitter/README.md b/frontend/magic-ui/components/MagicSplitter/README.md index ae9195396..f590890ea 100644 --- a/frontend/magic-ui/components/MagicSplitter/README.md +++ b/frontend/magic-ui/components/MagicSplitter/README.md @@ -1,3 +1,103 @@ +# MagicSplitter 🪄 Componente Pannello di Divisione Magico + +`MagicSplitter` è una versione migliorata del componente Splitter di Ant Design, che offre uno stile più pulito e una migliore esperienza utente. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ---------------- | ---- | ------------------ | ------------------------------------ | +| ...SplitterProps | - | - | Supporta tutte le proprietà di Ant Design Splitter | + +## Sottocomponenti + +- `MagicSplitter.Panel` - Sottocomponente pannello di divisione, utilizzato per definire ciascuna area ridimensionabile + +## Uso Base + +```tsx +import { MagicSplitter } from '@/components/base/MagicSplitter'; + +// Uso base - divisione orizzontale + + +
Contenuto pannello sinistro
+ + +
Contenuto pannello destro
+ + + +// Divisione verticale + + +
Contenuto pannello superiore
+ + +
Contenuto pannello inferiore
+ + + +// Impostare dimensioni predefinite + + +
Contenuto pannello sinistro (30%)
+ + +
Contenuto pannello destro (70%)
+ + + +// Pannelli multipli + + +
Primo pannello
+ + +
Secondo pannello
+ + +
Terzo pannello
+ + + +// Uso annidato + + +
Pannello sinistro
+ + + + +
Pannello destro superiore
+ + +
Pannello destro inferiore
+ + + + +``` + +## Caratteristiche ✨ + +1. **Design Pulito** 🧹: Rimossi gli stili predefiniti della barra di trascinamento, per un effetto visivo più pulito +2. **Trascinamento Senza Interruzioni** 🔄: Nessuna interferenza visiva durante il trascinamento della linea di divisione +3. **Layout Flessibile** 🏗️: Supporta divisione orizzontale e verticale, oltre all'uso annidato +4. **Margini Zero** 📏: I pannelli non hanno margini interni predefiniti, permettendo al contenuto di utilizzare pienamente lo spazio + +## Quando Usare + +- Quando è necessario creare layout ridimensionabili 📐 +- Quando è necessario dividere lo schermo in più aree interattive 🖥️ +- Quando si implementano interfacce come editor di codice, browser di file, ecc., che richiedono regolazioni flessibili dello spazio 💻 +- Quando gli utenti devono personalizzare le dimensioni di ciascuna area 🎛️ + +Il componente MagicSplitter rende i tuoi pannelli di divisione più puliti e user-friendly, mantenendo tutte le funzionalità di Ant Design Splitter. 🪄 + +--- + +## Testo Originale (Inglese e Cinese) + # MagicSplitter 魔法分割面板组件 `MagicSplitter` 是一个基于 Ant Design Splitter 组件的增强版分割面板，提供了更简洁的样式和更好的用户体验。 diff --git a/frontend/magic-ui/components/MagicStreamContent/README.md b/frontend/magic-ui/components/MagicStreamContent/README.md index b912789b9..8cf63f6bb 100644 --- a/frontend/magic-ui/components/MagicStreamContent/README.md +++ b/frontend/magic-ui/components/MagicStreamContent/README.md @@ -1,3 +1,60 @@ +# MagicStreamContent Componente di Contenuto in Streaming Magico 🪄 + +MagicStreamContent è un componente per visualizzare contenuti in streaming, che simula l'effetto di digitazione, mostrando il testo parola per parola, offrendo agli utenti un'esperienza di lettura dinamica. Questo componente è particolarmente adatto per risposte di chatbot, generazione di codice e altri scenari che richiedono una presentazione graduale dei contenuti. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | --------------------------------- | ------------------ | ----------------------------------------------- | +| content | string | - | Il contenuto di testo da visualizzare in streaming | +| children | (text: string) => React.ReactNode | - | Funzione di rendering opzionale per personalizzare la modalità di rendering del contenuto | + +## Utilizzo Base + +```tsx +import MagicStreamContent from '@/components/base/MagicStreamContent'; + +// Utilizzo base - visualizzazione diretta del testo + + +// Utilizzo con funzione di rendering personalizzata + + {(text) => {text}} + + +// Utilizzo in un'interfaccia di chat +
+
+ Bot +
+
+ +
+
+``` + +## Caratteristiche ✨ + +- **Effetto Digitazione** ⌨️: Simula un processo di digitazione reale, mostrando il contenuto parola per parola +- **Aggiornamento in Streaming** 🔄: Supporta aggiornamenti incrementali del contenuto, adatto per risposte API in streaming +- **Rendering Personalizzato** 🎨: Tramite la funzione children è possibile personalizzare la modalità di rendering del contenuto +- **Transizione Fluida** 🌊: Mantiene un effetto visivo fluido quando si aggiunge nuovo contenuto +- **Leggero** ⚡: Implementazione del componente semplice, con basso impatto sulle prestazioni + +## Scenari di Utilizzo 📋 + +- Visualizzazione delle risposte di chatbot AI 🤖 +- Visualizzazione dell'output di generatori di codice 💻 +- Presentazione graduale di contenuti tutoriali e guidati 📖 +- Visualizzazione dinamica di storie e narrazioni 📚 +- Qualsiasi presentazione di contenuti graduali che richieda di catturare l'attenzione dell'utente 👀 + +Il componente MagicStreamContent, attraverso la simulazione dell'effetto di digitazione, fornisce alle applicazioni un modo più vivace e coinvolgente per visualizzare i contenuti, particolarmente adatto per scenari che richiedono un senso di interazione in tempo reale. + +--- + +**Testo Originale (Cinese):** + # MagicStreamContent 魔法流式内容组件 MagicStreamContent 是一个用于展示流式内容的组件，它能够模拟打字效果，逐字显示文本内容，为用户提供动态的阅读体验。该组件特别适用于聊天机器人回复、代码生成等需要渐进式展示内容的场景。 diff --git a/frontend/magic-ui/components/MagicTable/README.md b/frontend/magic-ui/components/MagicTable/README.md index 1da72a2ad..e40d4c3b9 100644 --- a/frontend/magic-ui/components/MagicTable/README.md +++ b/frontend/magic-ui/components/MagicTable/README.md @@ -1,3 +1,106 @@ +# MagicTable Componente Tabella Magica 📊 + +`MagicTable` è una versione migliorata del componente Table di Ant Design, che offre un migliore stato di caricamento, comportamento di scorrimento e ottimizzazioni di stile. ✨ + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------------------------------------------------------ | ---------------------- | ----------------------------------- | +| loading | boolean \| SpinProps | false | Stato di caricamento della tabella | +| scroll | { x?: number \| string \| true; y?: number \| string } | { x: 'max-content' } | Configurazione scorrimento tabella | +| ...TableProps | - | - | Supporta tutte le proprietà di Ant Design Table | + +## Uso Base + +```tsx +import { MagicTable } from '@/components/base/MagicTable'; +import type { ColumnsType } from 'antd/es/table'; + +// Definire il tipo di dati +interface DataType { + key: string; + name: string; + age: number; + address: string; +} + +// Definire le colonne +const columns: ColumnsType = [ + { + title: 'Nome', + dataIndex: 'name', + key: 'name', + }, + { + title: 'Età', + dataIndex: 'age', + key: 'age', + }, + { + title: 'Indirizzo', + dataIndex: 'address', + key: 'address', + }, +]; + +// Definire i dati +const data: DataType[] = [ + { + key: '1', + name: 'Mario Rossi', + age: 32, + address: 'Via Roma, Milano', + }, + { + key: '2', + name: 'Luca Bianchi', + age: 42, + address: 'Via Garibaldi, Roma', + }, +]; + +// Uso base + + +// Stato di caricamento + + +// Scorrimento con altezza fissa + + +// Evento click sulla riga + ({ + onClick: () => console.log('Cliccata la riga:', record), + })} +/> +``` + +## Caratteristiche + +1. **Stato di caricamento ottimizzato** 🔄: Utilizza il componente MagicSpin per un effetto di caricamento più elegante +2. **Gestione automatica dello scorrimento** 📜: Imposta per default lo scorrimento x su 'max-content' per evitare compressioni del contenuto +3. **Stile click sulle righe** 👆: Aggiunge uno stile cursore alle righe della tabella per indicare che sono cliccabili +4. **Ottimizzazione stato vuoto** 🚫: Nasconde il prompt di stato vuoto durante il caricamento per evitare sfarfallii +5. **Controllo flessibile dell'altezza** 📏: Puoi controllare l'altezza fissa della tabella tramite la proprietà scroll.y + +## Quando Usare + +- Quando devi mostrare grandi quantità di dati strutturati 📈 +- Quando devi eseguire operazioni come ordinamento, filtraggio, paginazione 🔍 +- Quando la tabella necessita di una migliore visualizzazione dello stato di caricamento ⏳ +- Quando il contenuto della tabella deve essere scorrevole 📖 +- Quando le righe devono essere cliccabili 🖱️ + +Il componente MagicTable rende la visualizzazione delle tue tabelle più elegante e user-friendly, mantenendo tutte le potenti funzionalità di Ant Design Table. 🎉 + +## Testo Originale (Cinese) # MagicTable 魔法表格组件 `MagicTable` 是一个基于 Ant Design Table 组件的增强版表格，提供了更好的加载状态、滚动行为和样式优化。 diff --git a/frontend/magic-ui/components/MagicTag/README.md b/frontend/magic-ui/components/MagicTag/README.md index 4dbb92605..1b3f2bea2 100644 --- a/frontend/magic-ui/components/MagicTag/README.md +++ b/frontend/magic-ui/components/MagicTag/README.md @@ -1,3 +1,56 @@ +# MagicTag Componente Etichetta Magica ✨ + +`MagicTag` è una versione migliorata del componente Tag di Ant Design, che offre stili più belli e una migliore esperienza utente. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---- | ------------------ | ------------------------------------ | +| ...TagProps | - | - | Supporta tutte le proprietà di Ant Design Tag | + +## Uso Base + +```tsx +import { MagicTag } from '@/components/base/MagicTag'; + +// Etichetta base +Contenuto Etichetta + +// Etichetta chiudibile +Etichetta Chiudibile + +// Etichetta con colore +Etichetta Blu +Etichetta Rossa +Etichetta Verde +Etichetta Arancione + +// Etichetta con icona +}>Etichetta con Icona + +// Gestire evento di chiusura + console.log('Etichetta chiusa')}> + Clicca per Chiudere + +``` + +## Caratteristiche + +1. **Stili Ottimizzati** ✨: Angoli più arrotondati, colori di riempimento più morbidi, aspetto generale più bello +2. **Icona di Chiusura Personalizzata** 🔄: Utilizza il componente MagicIcon come icona di chiusura, per un effetto visivo più uniforme +3. **Layout Flessibile** 📐: Utilizza layout flex interno, assicurando l'allineamento centrato del contenuto +4. **Design Senza Bordi** 🎨: Utilizza bordi trasparenti per default, rendendo le etichette più moderne + +## Quando Usare + +- Quando devi mostrare dati etichettati 📋 +- Quando devi classificare dati 🏷️ +- Quando devi mostrare stati o attributi 📊 +- Quando gli utenti devono aggiungere o rimuovere etichette ✏️ + +Il componente MagicTag rende la presentazione delle tue etichette più bella e uniforme, mantenendo tutte le funzionalità di Ant Design Tag. + +## Testo Originale # MagicTag 魔法标签组件 `MagicTag` 是一个基于 Ant Design Tag 组件的增强版标签，提供了更美观的样式和更好的用户体验。 diff --git a/frontend/magic-ui/components/MagicUploadAction/README.md b/frontend/magic-ui/components/MagicUploadAction/README.md index dce926ea9..17cc48f60 100644 --- a/frontend/magic-ui/components/MagicUploadAction/README.md +++ b/frontend/magic-ui/components/MagicUploadAction/README.md @@ -1,3 +1,74 @@ +# UploadAction Componente Azione di Caricamento 📤 + +UploadAction è un componente di basso livello per gestire le interazioni di caricamento file. Incapsula la logica principale per la selezione dei file, fornendo un input file nascosto e un metodo per attivare la selezione, che può essere utilizzato con vari pulsanti personalizzati o aree di trascinamento. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---------------------------------------- | ------------------ | ------------------------------------------------------- | +| multiple | boolean | false | Se supportare la selezione di più file 📁 | +| handler | (trigger: () => void) => React.ReactNode | - | Per rendere l'elemento che attiva il caricamento, riceve una funzione trigger come parametro 🔄 | +| onFileChange | (files: File[]) => void | - | Funzione di callback dopo la selezione dei file, riceve l'array dei file selezionati 📂 | + +## Uso Base + +```tsx +import UploadAction from '@/opensource/components/base/UploadAction'; + +// Uso base - pulsante personalizzato per attivare il caricamento +const handleFileChange = (files: File[]) => { + console.log('File selezionati:', files); + // Gestisci la logica di caricamento file +}; + + ( + + )} +/> + +// Supporto per caricamento multi-file + ( + + )} +/> + +// Combinazione con altri componenti +import { Button } from 'antd'; + + ( + + )} +/> +``` + +## Caratteristiche + +- **Modalità di Attivazione Flessibile** 🔄: Personalizza l'elemento che attiva il caricamento tramite la proprietà handler +- **Input File Nascosto** 👁️‍🗨️: Nasconde l'input file nativo poco attraente +- **Supporto Multi-File** 📁: Abilita la selezione di più file con la proprietà multiple +- **Gestione File Semplificata** 📋: Gestisce automaticamente l'evento di selezione file e fornisce i file selezionati tramite callback +- **Riutilizzabilità** 🔄: Riutilizzabile in diversi scenari di caricamento + +## Scenari di Uso + +- Implementazione di pulsanti di caricamento personalizzati 🎨 +- Funzionalità di selezione file per aree di trascinamento 🖱️ +- Interfacce di caricamento che necessitano di nascondere l'input file nativo +- Come blocco di costruzione per componenti di caricamento più complessi 🏗️ +- Qualsiasi scenario interattivo che richieda la selezione di file 📂 + +Il componente UploadAction si concentra sulla logica principale della selezione file, senza includere stili o elementi visivi, rendendolo flessibile per combinarsi con vari elementi di interfaccia personalizzati, fornendo un'esperienza di caricamento file coerente per l'applicazione. + +## Testo Originale # UploadAction 上传动作组件 UploadAction 是一个用于处理文件上传交互的底层组件。它封装了文件选择的核心逻辑，提供了一个隐藏的文件输入框和触发文件选择的方法，可以与各种自定义上传按钮或拖拽区域配合使用。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicAppLoader/README.md b/frontend/magic-web/src/opensource/components/base/MagicAppLoader/README.md index 1bd405a36..770518a89 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicAppLoader/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicAppLoader/README.md @@ -1,3 +1,67 @@ +# MagicAppLoader Componente Caricatore di App Magiche 🚀 + +`MagicAppLoader` è un componente per caricare e visualizzare applicazioni microfrontend, che fornisce gestione dello stato di caricamento, gestione degli errori e animazioni di caricamento. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | -------------------- | ------------------ | ---------------------------------------- | +| appMeta | AppMeta | - | Metadati dell'app micro, inclusi nome, URL di ingresso, ecc. | +| onLoad | () => void | - | Funzione di callback per il caricamento riuscito dell'app | +| onError | (error: any) => void | - | Funzione di callback per il fallimento del caricamento dell'app | +| fallback | ReactNode | - | Contenuto da mostrare durante il caricamento, predefinito a un'animazione di caricamento | +| errorView | ReactNode | - | Contenuto da mostrare in caso di fallimento del caricamento | + +## Uso Base + +```tsx +import { MagicAppLoader } from '@/components/base/MagicAppLoader'; + +// Uso base +const appMeta = { + name: 'my-micro-app', + entry: 'https://example.com/micro-app/', + basename: '/my-app' +}; + + console.log('App caricata con successo')} + onError={(error) => console.error('Caricamento app fallito', error)} +/> + +// Personalizza stati di caricamento ed errore +Caricamento app in corso...} + errorView={
Caricamento app fallito, aggiorna e riprova
} +/> + +// Uso in un layout +
+ +
+``` + +## Caratteristiche ✨ + +1. **Supporto Microfrontend** 🚀: Progettato specificamente per caricare app microfrontend, supporta comunicazione tra app +2. **Gestione Stato** 📊: Gestione integrata dello stato di caricamento dell'app, gestisce automaticamente stati di caricamento ed errore +3. **Degradazione Elegante** 🔄: Fornisce vista di errore in caso di fallimento del caricamento, migliorando l'esperienza utente +4. **Animazione di Caricamento** 🎬: Animazione di caricamento integrata, fornisce feedback visivo +5. **Isolamento Sandbox** 🛡️: Supporta isolamento sandbox per app micro, previene conflitti di stile e variabili globali tra app + +## Quando Usare ❓ + +- Quando è necessario caricare un'app microfrontend nell'app principale +- Quando è necessario gestire stati di caricamento ed errori delle app micro +- Quando è necessario fornire una buona esperienza utente durante il caricamento dell'app +- Quando è necessario integrare app di terze parti nel sistema esistente +- Quando è necessario costruire un'architettura microfrontend scalabile + +Il componente MagicAppLoader semplifica il processo di caricamento e gestione delle app microfrontend, fornendo una gestione dello stato completa e un'esperienza utente eccellente, ed è la scelta ideale per costruire architetture microfrontend. + +## Testo Originale # MagicAppLoader 魔法应用加载器组件 `MagicAppLoader` 是一个用于加载和显示微前端应用的组件，提供了应用加载状态管理、错误处理和加载动画等功能。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicAvatar/README.md b/frontend/magic-web/src/opensource/components/base/MagicAvatar/README.md index f0e3f52b6..e5603fca8 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicAvatar/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicAvatar/README.md @@ -1,3 +1,68 @@ +# MagicAvatar ✨ Componente Avatar Magico + +`MagicAvatar` è una versione migliorata del componente Avatar di Ant Design, che offre generazione automatica di colori, supporto per badge e altro. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ----------------------------------------- | ------------------ | ------------------------------------ | +| badgeProps | BadgeProps | - | Proprietà del badge per mostrare un badge sull'avatar | +| size | number \| 'large' \| 'small' \| 'default' | 40 | Dimensione dell'avatar | +| shape | 'circle' \| 'square' | 'square' | Forma dell'avatar, predefinita quadrata | +| src | string | - | URL dell'immagine dell'avatar | +| ...AvatarProps | - | - | Supporta tutte le proprietà di Ant Design Avatar | + +## Uso Base + +```tsx +import { MagicAvatar } from '@/components/base/MagicAvatar'; + +// Uso base - con testo (tronca automaticamente i primi due caratteri) +Username + +// Con immagine + + +// Dimensione personalizzata +Avatar Grande +Avatar Piccolo + +// Con badge + + Utente + + +// Stile personalizzato +Personalizzato +``` + +## Caratteristiche + +1. **Generazione Automatica Colori** 🎨: Quando non viene fornita un'immagine, genera automaticamente colore di sfondo e testo basato sul contenuto. +2. **Supporto Badge** 🏷️: Aggiungi badge sull'avatar tramite `badgeProps` per mostrare stato o numeri. +3. **Troncamento Testo** ✂️: Tronca automaticamente i primi due caratteri del testo come contenuto avatar. +4. **Validazione URL** 🔗: Valida automaticamente se src è un URL valido, altrimenti torna al testo. +5. **Stile Uniforme** ✨: Fornisce bordi uniformi e ombre testo. + +## Quando Usare + +- Quando devi mostrare un avatar utente 👤 +- Quando devi mostrare stato o numero notifiche sull'avatar +- Quando devi generare avatar colorati automaticamente dal nome utente +- Quando devi mostrare identificatori utente in liste o commenti + +Il componente MagicAvatar rende la presentazione degli avatar più bella e intelligente, senza bisogno di immagini per ogni utente, offrendo effetti personalizzati. + +--- + +## Testo Originale (Inglese) + # MagicAvatar 魔法头像组件 `MagicAvatar` 是一个基于 Ant Design Avatar 组件的增强版头像组件，提供了自动生成颜色、徽章支持等功能。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicBlock/README.md b/frontend/magic-web/src/opensource/components/base/MagicBlock/README.md index bab4369f5..a3b29fc7b 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicBlock/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicBlock/README.md @@ -1,3 +1,62 @@ +# MagicBlock Componente Blocco Magico 🪄 + +`MagicBlock` è un semplice componente blocco di contenuto modificabile, che fornisce un contenitore div con proprietà `contentEditable`, permettendo agli utenti di modificare direttamente il contenuto al suo interno. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------------------------------ | ------------------ | ------------------------------------ | +| children | ReactNode | - | Contenuto visualizzato nel blocco | +| ...props | HTMLAttributes | - | Supporta tutte le proprietà HTML del div | + +## Uso Base + +```tsx +import MagicBlock from '@/components/base/MagicBlock'; + +// Uso base +Contenuto modificabile + +// Impostare stili + + Contenuto modificabile con stili + + +// Aggiungere gestori di eventi + console.log('Modifica completata', e.currentTarget.textContent)} + onInput={(e) => console.log('Contenuto cambiato', e.currentTarget.textContent)} +> + Contenuto modificabile con gestori di eventi + +``` + +## Caratteristiche ✨ + +1. **Semplice e Leggero** 📏: Fornisce funzionalità di modifica contenuto di base, senza controlli di formato complessi +2. **Facile da Integrare** 🔗: Può essere facilmente integrato in vari scenari che richiedono modifica contenuto +3. **Completamente Personalizzabile** 🎨: Supporta tutte le proprietà HTML del div, permettendo personalizzazione di stili e comportamenti secondo necessità +4. **Riferimento Trasparente** 🔍: Usa useRef per mantenere il riferimento all'elemento DOM, facilitando operazioni esterne + +## Quando Usare + +- Quando è necessaria una funzionalità di modifica contenuto semplice +- Quando gli utenti devono poter modificare direttamente il testo sulla pagina +- Per scenari di modifica semplici che non richiedono funzionalità di editing rich text complesse +- Quando è necessario personalizzare l'aspetto e il comportamento dell'area di modifica + +Il componente MagicBlock fornisce una soluzione semplice e flessibile per la modifica contenuto, adatta a vari scenari che richiedono funzionalità di modifica testo di base. 🚀 + +--- + +**Testo Originale (Cinese e Inglese):** + # MagicBlock 魔法块组件 `MagicBlock` 是一个简单的可编辑内容块组件，提供了一个具有 `contentEditable` 属性的 div 容器，允许用户直接编辑其中的内容。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicButton/README.md b/frontend/magic-web/src/opensource/components/base/MagicButton/README.md index af121f28c..8bd53513a 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicButton/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicButton/README.md @@ -1,3 +1,61 @@ +# MagicButton Componente Pulsante Magico ✨ + +`MagicButton` è una versione migliorata del componente Button di Ant Design, che offre più opzioni di personalizzazione e ottimizzazioni stilistiche. 🔘 + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------------------------------- | ------------------ | ------------------------------------ | +| justify | CSSProperties["justifyContent"] | "center" | Allineamento orizzontale del contenuto del pulsante | +| theme | boolean | true | Se applicare gli stili del tema | +| tip | ReactNode | - | Contenuto del suggerimento mostrato al passaggio del mouse | +| ...ButtonProps | - | - | Supporta tutte le proprietà del Button di Ant Design | + +## Uso Base + +```tsx +import { MagicButton } from '@/components/base/MagicButton'; + +// Pulsante base +Cliccami + +// Pulsante con icona +}>Preferiti + +// Pulsante con suggerimento +Passa il mouse per vedere il suggerimento + +// Allineamento personalizzato +Contenuto allineato a sinistra + +// Senza stili del tema +Senza stili del tema + +// Diversi tipi di pulsante +Pulsante Principale +Pulsante Predefinito +Pulsante Tratteggiato +Pulsante Link +Pulsante Testo +``` + +## Caratteristiche + +1. **Controllo Stilistico Migliorato** 🎨: Offre più opzioni di personalizzazione stilistica, come l'allineamento del contenuto +2. **Funzione Suggerimento Integrata** 💡: Tramite la proprietà `tip` puoi facilmente aggiungere suggerimenti al passaggio del mouse +3. **Integrazione Tema** 🌟: Puoi controllare se applicare gli stili del tema con la proprietà `theme` +4. **Supporto Icone Flessibile** 🖼️: Completamente compatibile con il sistema di icone di Ant Design + +## Quando Usare + +- Quando devi posizionare un pulsante sulla pagina 📄 +- Quando hai bisogno di un migliore controllo stilistico sul pulsante 🎯 +- Quando il pulsante deve avere un suggerimento al passaggio del mouse 🖱️ +- Quando il contenuto del pulsante necessita di un allineamento specifico 📐 + +Il componente MagicButton rende i tuoi pulsanti più flessibili e belli, mantenendo tutte le funzionalità del pulsante di Ant Design. 🚀 + +## Testo Originale # MagicButton 魔法按钮组件 `MagicButton` 是一个基于 Ant Design Button 组件的增强版按钮，提供了更多的自定义选项和样式优化。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicCheckFavor/README.md b/frontend/magic-web/src/opensource/components/base/MagicCheckFavor/README.md index c019cc7cc..84da5154c 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicCheckFavor/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicCheckFavor/README.md @@ -1,3 +1,65 @@ +# MagicCheckFavor Componente Magico di Preferenza ✨ + +MagicCheckFavor è un componente di casella di controllo con stile personalizzato, progettato specificamente per scenari come preferiti e impostazioni di preferenza. Questo componente fornisce un elemento interattivo selezionabile/non selezionabile, con uno stile visivo speciale che lo rende più intuitivo nelle funzionalità relative ai preferiti. ⭐ + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | -------------------------- | ------------------ | ------------------------------- | +| checked | boolean | false | Se è selezionato | +| onChange | (checked: boolean) => void | - | Funzione di callback quando lo stato selezionato cambia | + +## Uso Base + +```tsx +import MagicCheckFavor from '@/components/base/MagicCheckFavor'; +import { useState } from 'react'; + +// Uso base +const [isChecked, setIsChecked] = useState(false); + + setIsChecked(checked)} +/> + +// Selezionato per default + console.log('Stato selezionato:', checked)} +/> + +// Uso in un elemento di lista +
+ Progetto Preferito + handleFavoriteChange(item.id, checked)} + /> +
+``` + +## Caratteristiche + +- **Stile Personalizzato** 🎨: Diverso dalle caselle di controllo tradizionali, offre un aspetto più adatto agli scenari di preferiti +- **Semplice da Usare** 👍: API progettata in modo semplice, facile da utilizzare +- **Gestione Stato** 🔄: Supporta modalità controllata, può controllare lo stato selezionato tramite stato esterno +- **Feedback Interattivo** 💫: Fornisce feedback visivo intuitivo, migliorando l'esperienza utente +- **Leggero** 🪶: Implementazione del componente semplice, senza dipendenze aggiuntive + +## Scenari di Uso + +- Selezione di elementi nei preferiti +- Elemento interattivo per funzionalità di like/preferiti +- Opzioni di interruttore nelle impostazioni di preferenza +- Qualsiasi elemento di interfaccia che necessita di rappresentare uno stato di "preferito" o "like" ❤️ + +Il componente MagicCheckFavor, fornendo una casella di controllo visivamente più adatta agli scenari di preferiti, permette agli utenti di ottenere un feedback più intuitivo durante le operazioni di preferiti, elevando l'esperienza utente complessiva. 🌟 + +--- + +## Testo Originale (Inglese) + # MagicCheckFavor 魔法复选组件 MagicCheckFavor 是一个自定义样式的复选框组件，专为收藏夹和偏好设置等场景设计。该组件提供了一个可选中/取消选中的交互元素，具有特殊的视觉样式，使其在收藏相关功能中更加直观。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicCollapse/README.md b/frontend/magic-web/src/opensource/components/base/MagicCollapse/README.md index 317c01070..ffbadbb06 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicCollapse/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicCollapse/README.md @@ -1,3 +1,85 @@ +# MagicCollapse Componente Pannello Collassabile Magico 📖 + +`MagicCollapse` è una versione migliorata del componente Collapse di Ant Design, che offre stili più belli e una migliore esperienza utente. 🔧 + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ---------------- | ---- | ------------------ | ------------------------------------ | +| ...CollapseProps | - | - | Supporta tutte le proprietà di Ant Design Collapse | + +## Uso Base + +```tsx +import { MagicCollapse } from '@/components/base/MagicCollapse'; +import { Collapse } from 'antd'; + +const { Panel } = Collapse; + +// Uso base + + +

Questo è il contenuto del pannello 1

+ + +

Questo è il contenuto del pannello 2

+ + +

Questo è il contenuto del pannello 3

+ + + +// Espandi pannelli specifici per default + + +

Questo è il contenuto del pannello espanso per default

+ + +

Questo è il contenuto del pannello chiuso per default

+ + + +// Modalità fisarmonica (solo un pannello espanso alla volta) + + +

Contenuto pannello fisarmonica 1

+ + +

Contenuto pannello fisarmonica 2

+ + + +// Ascolta eventi di espansione/collasso + console.log('Pannello attualmente espanso:', key)}> + +

Contenuto pannello 1

+ + +

Contenuto pannello 2

+ + +``` + +## Caratteristiche ✨ + +1. **Stili ottimizzati** 🎨: Usa la modalità ghost, rimuove i bordi per un aspetto più pulito e bello. +2. **Icona di espansione personalizzata** 🔄: Usa il componente MagicIcon come icona di espansione per un effetto visivo più uniforme. +3. **Animazione fluida** 🌊: Effetto di rotazione fluida durante espansione/collasso. +4. **Layout flessibile** 📐: Icona di espansione sul lato destro, in linea con le tendenze di design moderne. + +## Quando Usare ❓ + +- Quando devi raggruppare contenuti complessi per la visualizzazione 📂 +- Quando devi risparmiare spazio sulla pagina, collassando i contenuti 🗂️ +- Quando devi creare un effetto fisarmonica (solo un pannello espanso alla volta) 🎼 +- Quando devi mostrare informazioni categorizzate, permettendo agli utenti di visualizzarle su richiesta 📋 + +Il componente MagicCollapse rende i tuoi pannelli collassabili più belli e user-friendly, mantenendo tutte le funzionalità di Ant Design Collapse. 🚀 + +--- + +**Testo Originale (Cinese e Inglese):** + # MagicCollapse 魔法折叠面板组件 `MagicCollapse` 是一个基于 Ant Design Collapse 组件的增强版折叠面板，提供了更美观的样式和更好的用户体验。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicDropdown/README.md b/frontend/magic-web/src/opensource/components/base/MagicDropdown/README.md index 536a420ae..abde9ded6 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicDropdown/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicDropdown/README.md @@ -1,3 +1,96 @@ +# MagicDropdown Componente Dropdown Magico 📋 + +`MagicDropdown` è una versione migliorata del componente Dropdown di Ant Design, che offre stili più belli e una migliore esperienza utente. + +## Proprietà 📋 + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ---------------- | --------- | ------------------ | ---------------------------------------- | +| menu | MenuProps | - | Configurazione del menu, per definire il contenuto e il comportamento del dropdown | +| overlayClassName | string | - | Classe personalizzata per il dropdown | +| ...DropDownProps | - | - | Supporta tutte le proprietà di Ant Design Dropdown | + +## Uso Base 💡 + +```tsx +import { MagicDropdown } from '@/components/base/MagicDropdown'; +import { Button, Space } from 'antd'; +import type { MenuProps } from 'antd'; +import { IconSettings, IconUser, IconLogout } from '@tabler/icons-react'; + +// Definire gli elementi del menu +const items: MenuProps['items'] = [ + { + key: '1', + label: 'Informazioni Personali', + icon: , + }, + { + key: '2', + label: 'Impostazioni', + icon: , + }, + { + type: 'divider', + }, + { + key: '3', + label: 'Esci dal Login', + icon: , + danger: true, + }, +]; + +// Uso base + + + + +// Con modalità di attivazione + + + + +// Con freccia + + + + +// Con gestione eventi + console.log('Cliccato elemento menu:', e.key), + }} +> + + + +// Stato disabilitato + + + +``` + +## Caratteristiche ✨ + +1. **Stili Ottimizzati** 🎨: Angoli più arrotondati, spaziatura più ragionevole ed effetti hover più belli +2. **Ottimizzazione Spaziatura Icone** 📏: Migliorata la spaziatura tra icone e testo per un layout più armonioso +3. **Miglioramento Stili Elementi Pericolosi** ⚠️: Forniti segnali visivi più evidenti per operazioni pericolose +4. **Ottimizzazione Posizione Sottomenu** 📍: Regolata la posizione dei sottomenu per una visualizzazione più naturale +5. **Adattamento Tema** 🌙: Adatta automaticamente temi chiari/scuri, fornendo un'esperienza visiva coerente + +## Quando Usare ❓ + +- Quando hai bisogno di posizionare un dropdown nella pagina +- Quando vuoi fornire all'utente molteplici opzioni operative senza occupare troppo spazio +- Quando hai bisogno di raggruppare operazioni correlate +- Quando il dropdown include operazioni pericolose +- Quando desideri uno stile di dropdown più bello + +Il componente MagicDropdown rende i tuoi dropdown più belli e facili da usare, mantenendo tutte le funzionalità di Ant Design Dropdown. + +## Testo Originale (Cinese e Inglese) # MagicDropdown 魔法下拉菜单组件 `MagicDropdown` 是一个基于 Ant Design Dropdown 组件的增强版下拉菜单，提供了更美观的样式和更好的用户体验。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicEllipseWithTooltip/README.md b/frontend/magic-web/src/opensource/components/base/MagicEllipseWithTooltip/README.md index 89b8f3329..8942f17a0 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicEllipseWithTooltip/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicEllipseWithTooltip/README.md @@ -1,3 +1,96 @@ +# MagicEllipseWithTooltip Componente di Ellissi Magica con Tooltip ✨ + +`MagicEllipseWithTooltip` è un componente intelligente per l'ellissi del testo, che mostra automaticamente i puntini di sospensione quando il testo supera la larghezza specificata e visualizza il testo completo tramite un tooltip al passaggio del mouse 📏. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ----------------- | ------ | ------------------ | --------------------------------------------------------- | +| text | string | - | Il contenuto del testo da visualizzare | +| maxWidth | string | - | Larghezza massima del testo, la parte eccedente viene sostituita con puntini di sospensione, es. "200px", "50%" | +| ...HTMLAttributes | - | - | Supporta tutti gli attributi dell'elemento HTML div | + +## Uso Base + +```tsx +import { MagicEllipseWithTooltip } from '@/components/base/MagicEllipseWithTooltip'; + +// Uso base + + +// Stile personalizzato + + +// Utilizzo in una cella di tabella +
( + + ), + }, + // Altre colonne... + ]} + dataSource={data} +/> + +// Utilizzo in un elemento di lista + ( + + + + )} +/> + +// Gestione eventi + console.log('Il testo è stato cliccato')} +/> +``` + +## Caratteristiche + +1. **Rilevamento Intelligente** 🧠: Mostra il tooltip solo quando il testo effettivamente trabocca +2. **Design Semplice** 🎨: Utilizza ellissi su una sola riga per mantenere l'interfaccia pulita +3. **Configurazione Flessibile** 🔧: Puoi impostare la larghezza massima per adattarsi a vari layout +4. **Completamente Personalizzabile** 🎛️: Supporta tutti gli attributi e stili dell'elemento div + +## Quando Usare + +- Quando devi visualizzare testi potenzialmente lunghi in uno spazio limitato 📝 +- Quando vuoi mantenere l'interfaccia pulita senza perdere informazioni 🧹 +- In tabelle, liste, carte e altri componenti per mostrare titoli o descrizioni 📋 +- Quando devi assicurarti che gli utenti possano vedere il contenuto completo del testo troncato 👀 + +Il componente MagicEllipseWithTooltip rende la visualizzazione dei tuoi testi lunghi più elegante e user-friendly, mantenendo l'interfaccia pulita e garantendo l'integrità delle informazioni. 🌟 + +--- + +**Testo Originale (Cinese):** + # MagicEllipseWithTooltip 魔法省略提示组件 `MagicEllipseWithTooltip` 是一个智能的文本省略组件，当文本超出指定宽度时自动显示省略号，并在鼠标悬停时通过工具提示显示完整文本。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicEmoji/README.md b/frontend/magic-web/src/opensource/components/base/MagicEmoji/README.md index 0f01eec02..97a84e822 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicEmoji/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicEmoji/README.md @@ -1,3 +1,55 @@ +# MagicEmoji Componente Emoji Magico 😊 + +MagicEmoji è un semplice componente per il rendering di immagini emoji, utilizzato per visualizzare simboli emoji nell'interfaccia. Il componente è basato sul tag HTML img, supporta attributi personalizzati come codice emoji, namespace e suffisso. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------ | ------------------ | ------------------------------------------- | +| code | string | - | Il codice univoco dell'emoji, obbligatorio | +| ns | string | "emojis/" | Il namespace dell'emoji, per costruire il percorso dell'immagine emoji | +| suffix | string | ".png" | Il suffisso del file immagine emoji | +| size | number | - | La dimensione dell'immagine emoji | + +Inoltre, il componente supporta tutti gli attributi del tag HTML img tranne `src` e `alt`. + +## Uso Base + +```tsx +import MagicEmoji from '@/components/base/MagicEmoji'; + +// Uso base + + +// Namespace e suffisso personalizzati + + +// Impostare la dimensione dell'emoji + + +// Aggiungere altri attributi img + +``` + +## Caratteristiche + +- **Semplice da usare** 😄: Basta fornire il codice emoji per renderizzare l'immagine emoji +- **Altamente personalizzabile** 🎨: Supporta namespace personalizzati, suffisso file e dimensione +- **Flessibilità** 🔧: Supporta tutti gli attributi standard del tag img +- **Leggero** ⚡: Implementazione del componente semplice, senza dipendenze aggiuntive + +## Scenari di Uso + +- Visualizzare simboli emoji nell'interfaccia di chat 💬 +- Inserire emoji in un editor di testo ricco 📝 +- Aggiungere elementi emozionali nell'interfaccia utente 😊 +- Usare emoji per esprimere emozioni in commenti o sistemi di feedback 👍 + +Il componente MagicEmoji è progettato per essere semplice, facile da integrare in vari scenari che richiedono la visualizzazione di emoji. Fornendo un'interfaccia unificata per il rendering di emoji, garantisce consistenza e manutenibilità nell'applicazione. + +--- + +## Testo Originale (Cinese) # MagicEmoji 魔法表情组件 MagicEmoji 是一个简单的表情图片渲染组件，用于在界面中显示表情符号。该组件基于 HTML 的 img 标签实现，支持自定义表情代码、命名空间和后缀等属性。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicEmojiPanel/README.md b/frontend/magic-web/src/opensource/components/base/MagicEmojiPanel/README.md index 687b2fd76..14469b163 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicEmojiPanel/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicEmojiPanel/README.md @@ -1,3 +1,77 @@ +# MagicEmojiPanel Componente Pannello Emoji Magico 😀 + +MagicEmojiPanel è un componente pannello di selezione emoji ricco di funzionalità, utilizzato per fornire funzionalità di selezione emoji nelle applicazioni. Questo componente mostra una serie di emoji cliccabili e supporta il passaggio tra diversi tipi di pannelli emoji (come emoji normali e emoji preferiti). 📱 + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | -------------------------- | ------------------ | ------------------------------------------------- | +| onClick | (emoji: EmojiInfo) => void | - | Funzione di callback quando si clicca su un emoji, con parametro le informazioni dell'emoji selezionato | + +Dove la definizione del tipo EmojiInfo è la seguente: + +```typescript +export type EmojiInfo = { + /** Codice emoji */ + code: string + /** Namespace emoji */ + ns: string + /** Suffisso emoji */ + suffix?: string + /** Tonalità della pelle */ + tone?: string + /** Dimensione emoji */ + size?: number +} +``` + +## Uso Base + +```tsx +import MagicEmojiPanel from "@/components/base/MagicEmojiPanel" +import type { EmojiInfo } from "@/components/base/MagicEmojiPanel/types" + +// Uso base +const handleEmojiClick = (emoji: EmojiInfo) => { + console.log("Emoji selezionato:", emoji) + // Gestisci la logica di selezione emoji +} + +; + +// Utilizzo in un popover +import { Popover } from "antd" +;} + trigger="click" + styles={{ + body: { + padding: 0, + }, + }} +> + + +``` + +## Caratteristiche + +- **Raccolta ricca di emoji** 🎉: Emoji integrati vari per la scelta degli utenti +- **Passaggio tra categorie** 🔄: Supporta il passaggio tra diversi tipi di pannelli emoji +- **Interfaccia accattivante** ✨: Interfaccia progettata con cura, inclusa area di scorrimento e barra di passaggio in basso +- **Callback personalizzato** ⚙️: Personalizza il comportamento dopo la selezione emoji tramite la proprietà onClick +- **Layout responsivo** 📐: Emoji disposti in griglia, adattabili a contenitori di dimensioni diverse + +## Scenari d'Uso + +- Selettore emoji in app di chat 💬 +- Input emoji nell'area commenti dei social media 📱 +- Funzione di inserimento emoji in editor di testo ricchi ✏️ +- Qualsiasi scenario interattivo che richieda la selezione di emoji da parte degli utenti + +Il componente MagicEmojiPanel fornisce una soluzione completa per la selezione di emoji, facilmente integrabile in varie applicazioni che necessitano di funzionalità di input emoji, migliorando l'esperienza utente e il divertimento interattivo. 🚀 + +## Testo Originale # MagicEmojiPanel 魔法表情面板组件 MagicEmojiPanel 是一个功能丰富的表情选择面板组件，用于在应用中提供表情选择功能。该组件展示了一系列可点击的表情，并支持切换不同类型的表情面板（如普通表情和喜欢表情）。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicEmpty/README.md b/frontend/magic-web/src/opensource/components/base/MagicEmpty/README.md index 9da2ac8ef..d06b6ebb8 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicEmpty/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicEmpty/README.md @@ -1,3 +1,55 @@ +# MagicEmpty Componente Stato Vuoto Magico 📄 + +`MagicEmpty` è una versione semplificata del componente Empty di Ant Design, che offre supporto per l'internazionalizzazione e uno stile predefinito pulito. 🌍 + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---- | ------------------ | ------------------------------------ | +| ...EmptyProps | - | - | Supporta tutte le proprietà di Empty di Ant Design | + +## Utilizzo Base + +```tsx +import { MagicEmpty } from '@/components/base/MagicEmpty'; + +// Utilizzo base + + +// Descrizione personalizzata (sovrascrive il testo internazionalizzato) + + +// Immagine personalizzata + + +// Utilizzo in liste o tabelle +
+ +
+ +// Con pulsante di azione + + + +``` + +## Caratteristiche ✨ + +1. **Supporto Internazionalizzazione** 🌐: Utilizza automaticamente il testo tradotto i18n per "Nessun dato" +2. **Stile Pulito** 🎨: Utilizza Empty.PRESENTED_IMAGE_SIMPLE come immagine predefinita per maggiore semplicità +3. **Facilità d'Uso** 🚀: Pronto all'uso senza configurazioni aggiuntive +4. **Completamente Personalizzabile** 🔧: Supporta tutte le proprietà del componente Empty di Ant Design + +## Quando Utilizzare + +- Quando una pagina o contenitore non ha dati 📭 +- Quando i risultati di ricerca o filtro sono vuoti 🔍 +- Quando liste, tabelle o insiemi di risultati sono vuoti 📊 +- Quando è necessario suggerire all'utente di creare il primo contenuto ➕ + +Il componente MagicEmpty rende la visualizzazione dello stato vuoto più pulita e internazionalizzata, adatto a vari scenari. 👍 + +## Testo Originale # MagicEmpty 魔法空状态组件 `MagicEmpty` 是一个基于 Ant Design Empty 组件的简化版空状态组件，提供了国际化支持和简洁的默认样式。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicEmptyFavor/README.md b/frontend/magic-web/src/opensource/components/base/MagicEmptyFavor/README.md index 6738d84fc..c086c55f9 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicEmptyFavor/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicEmptyFavor/README.md @@ -1,3 +1,49 @@ +# MagicEmptyFavor Componente Vuoto Preferiti Magico + +MagicEmptyFavor è un componente utilizzato per visualizzare lo stato vuoto dei preferiti. Quando la lista dei preferiti dell'utente è vuota, questo componente mostra un messaggio amichevole e un'icona, migliorando l'esperienza utente. ❤️ + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------ | ------------------ | ------------------------------------------------------- | +| text | string | - | Testo personalizzato da visualizzare; se non fornito, usa il testo di internazionalizzazione predefinito | + +## Uso Base + +```tsx +import MagicEmptyFavor from '@/components/base/MagicEmptyFavor'; + +// Uso base - con testo predefinito + + +// Testo personalizzato + + +// In rendering condizionale +{favoritesList.length === 0 && } +``` + +## Caratteristiche + +- **Prompt amichevole per stato vuoto** 💬: Fornisce feedback visivo, evitando pagine bianche +- **Supporto internazionalizzazione** 🌍: Testo predefinito supporta più lingue +- **Design semplice** ✨: Usa una combinazione semplice di icona e testo +- **Testo personalizzabile** ✏️: Supporta testo di visualizzazione personalizzato +- **Leggero** 🪶: Implementazione semplice del componente, senza dipendenze aggiuntive + +## Scenari d'Uso + +- Visualizzazione dello stato quando la lista dei preferiti o dei favoriti è vuota +- Prompt quando l'utente non ha ancora aggiunto alcun contenuto +- Prompt amichevole quando i risultati di ricerca sono vuoti +- Qualsiasi scenario che necessita di mostrare uno stato "nessun dato" + +Il componente MagicEmptyFavor migliora l'esperienza utente quando si affronta una lista vuota fornendo un prompt di stato vuoto visivamente accattivante, incoraggiando al contempo gli utenti ad aggiungere contenuti ai preferiti. 📚 + +--- + +**Testo Originale (Inglese/Cinese):** + # MagicEmptyFavor 魔法空收藏组件 MagicEmptyFavor 是一个用于显示收藏夹为空状态的组件。当用户的收藏列表为空时，该组件会显示一个友好的提示信息和图标，提升用户体验。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicIcon/README.md b/frontend/magic-web/src/opensource/components/base/MagicIcon/README.md index 095e49d44..dbfb78f5d 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicIcon/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicIcon/README.md @@ -1,3 +1,60 @@ +# MagicIcon Componente Icona Magica 🪄 + +`MagicIcon` è un componente wrapper basato su Tabler Icons, che fornisce adattamento al tema e controllo uniforme degli stili. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ----------------------------------------------------------------------- | ------------------ | ------------------------------- | +| component | ForwardRefExoticComponent & RefAttributes> | - | Il componente icona Tabler da renderizzare | +| active | boolean | false | Se è in stato attivo | +| animation | boolean | false | Se abilitare l'effetto animazione | +| ...IconProps | - | - | Supporta tutte le proprietà di Tabler Icons | + +## Uso Base + +```tsx +import { MagicIcon } from '@/components/base/MagicIcon'; +import { IconHome, IconStar, IconSettings } from '@tabler/icons-react'; + +// Icona base + + +// Dimensione personalizzata + + +// Colore personalizzato (sovrascrive il colore del tema) + + +// Spessore linea personalizzato + + +// Stato attivo + + +// Con effetto animazione (se implementato) + +``` + +## Caratteristiche ✨ + +1. **Adattamento al Tema** 🎨: Regola automaticamente il colore dell'icona in base al tema corrente (chiaro/scuro) +2. **Stile Uniforme** 📏: Fornisce spessore linea e colore uniformi per default +3. **Sicurezza dei Tipi** 🔒: Supporto completo per TypeScript con definizioni di tipo complete +4. **Estensione Flessibile** 🔧: Facilita la personalizzazione delle varie caratteristiche dell'icona tramite proprietà + +## Quando Usare + +- Quando hai bisogno di usare icone Tabler nella tua app 📱 +- Quando vuoi che le icone si adattino automaticamente ai cambiamenti di tema 🌗 +- Quando vuoi gestire uniformemente gli stili delle icone 🎯 +- Quando vuoi aggiungere stati interattivi alle icone (come stato attivo) ⚡ + +Il componente MagicIcon rende l'uso delle icone più semplice e uniforme, assicurando che si adattino alle impostazioni del tema della tua app. 🌟 + +--- + +## Testo Originale (Cinese) # MagicIcon 魔法图标组件 `MagicIcon` 是一个基于 Tabler Icons 的图标包装组件，提供了主题适配和统一的样式控制。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicImagePreview/README.md b/frontend/magic-web/src/opensource/components/base/MagicImagePreview/README.md index b33cd89ec..a1e0e7c94 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicImagePreview/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicImagePreview/README.md @@ -1,3 +1,98 @@ +# MagicImagePreview Componente di Anteprima Immagini Magiche 🖼️ + +`MagicImagePreview` è un componente di anteprima immagini ricco di funzionalità, che offre interazioni come zoom, rotazione, trascinamento e confronto, adatto a scenari in cui è necessario esaminare immagini in dettaglio. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| ----------------- | ------------------------------- | ------------------ | ------------------------------- | +| src | string | - | URL sorgente dell'immagine | +| onNext | () => void | - | Callback per l'immagine successiva | +| onPrev | () => void | - | Callback per l'immagine precedente | +| nextDisabled | boolean | false | Disabilita il pulsante successivo | +| prevDisabled | boolean | false | Disabilita il pulsante precedente | +| rootClassName | string | - | Classe personalizzata per il contenitore radice | +| hasCompare | boolean | false | Abilita la funzionalità di confronto immagini | +| viewType | CompareViewType | - | Tipo di vista confronto | +| onChangeViewType | (type: CompareViewType) => void | - | Callback per cambio tipo vista confronto | +| onLongPressStart | () => void | - | Callback inizio pressione lunga (per modalità confronto) | +| onLongPressEnd | () => void | - | Callback fine pressione lunga (per modalità confronto) | +| ...HTMLAttributes | - | - | Supporta tutti gli attributi dell'elemento HTML img | + +### Enumerazione CompareViewType + +| Valore | Descrizione | +| ---------- | ------------------- | +| PULL | Modalità confronto trascinamento 🔄 | +| LONG_PRESS | Modalità confronto pressione lunga ⏳ | + +## Utilizzo Base + +```tsx +import { MagicImagePreview } from '@/components/base/MagicImagePreview'; + +// Utilizzo base + + Immagine anteprima + + +// Anteprima immagine con pulsanti navigazione + + Immagine anteprima + + +// Con funzionalità confronto immagini + +
+ Immagine originale + Immagine confronto +
+ + +// Stili personalizzati + + Immagine anteprima + +``` + +## Caratteristiche + +1. **Barra strumenti interattiva multifunzione** 🔧: Offre funzioni come zoom, rotazione, reset e altre operazioni sulle immagini +2. **Trascinamento** 🖱️: Supporta il movimento dell'immagine tramite trascinamento del mouse +3. **Zoom con rotella** 🔍: Permette lo zoom dell'immagine usando la rotella del mouse +4. **Confronto immagini** ⚖️: Supporta due modalità di confronto - trascinamento e pressione lunga +5. **Navigazione immagini** ⬅️➡️: Supporta navigazione avanti e indietro in collezioni di immagini +6. **Design responsivo** 📱: Si adatta a contenitori di dimensioni diverse +7. **Adattamento tema scuro** 🌙: La barra strumenti si adatta automaticamente al tema scuro +8. **Riconoscimento immagini lunghe** 📜: Riconosce automaticamente e gestisce adeguatamente la visualizzazione di immagini lunghe + +## Quando Usare + +- Quando è necessario esaminare in dettaglio il contenuto delle immagini 👀 +- Quando è necessario eseguire operazioni come zoom e rotazione sulle immagini 🔄 +- Quando è necessario confrontare le differenze tra due immagini (es. immagine originale vs. elaborata) ⚖️ +- Quando è necessario sfogliare più immagini in una collezione ⬅️➡️ +- Quando è necessario fornire una funzionalità professionale di anteprima immagini in un'applicazione 🖼️ +- Quando è necessario visualizzare dettagli di immagini ad alta risoluzione 📸 + +Il componente MagicImagePreview offre un'esperienza professionale di anteprima immagini, ideale per scenari che richiedono un esame dettagliato del contenuto, come gallerie di immagini, app di editing foto, presentazioni di prodotti, ecc. + +## Testo Originale # MagicImagePreview 魔法图片预览组件 `MagicImagePreview` 是一个功能丰富的图片预览组件，提供缩放、旋转、拖拽、对比等多种交互功能，适用于需要详细查看图片的场景。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicMarkmap/README.md b/frontend/magic-web/src/opensource/components/base/MagicMarkmap/README.md index d3fb07bbc..eb8cabbf1 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicMarkmap/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicMarkmap/README.md @@ -1,3 +1,90 @@ +# MagicMarkmap 🧙‍♂️ Componente Magico per Mappa Mentale + +`MagicMarkmap` è un componente per rendere e visualizzare mappe mentali, basato sulla libreria Markmap, che supporta la conversione di testo in formato Markdown in mappe mentali interattive. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------- | ------------------ | ------------------------------------ | +| content | string | - | Contenuto della mappa mentale in formato Markdown | +| readonly | boolean | false | Se è in modalità sola lettura, non permette modifiche | +| ...rest | - | - | Supporta il passaggio di altre proprietà HTML all'elemento contenitore | + +## Uso Base + +```tsx +import { MagicMarkmap } from '@/components/base/MagicMarkmap'; + +// Uso base +const markdownContent = ` +# Piano Progetto +## Fase Uno +### Analisi Requisiti +### Progettazione Prototipo +## Fase Due +### Sviluppo +### Test +## Fase Tre +### Distribuzione +### Manutenzione +`; + + + +// Modalità sola lettura + + +// Stile personalizzato + +``` + +## Formato Mappa Mentale + +MagicMarkmap utilizza la struttura dei titoli Markdown per definire i livelli dei nodi della mappa mentale: + +```markdown +# Nodo Radice + +## Nodo Livello 2-1 + +### Nodo Livello 3-1-1 + +### Nodo Livello 3-1-2 + +## Nodo Livello 2-2 + +### Nodo Livello 3-2-1 + +#### Nodo Livello 4-2-1-1 +``` + +Ogni titolo diventa un nodo nella mappa mentale, e il livello del titolo determina il livello del nodo nella mappa mentale. + +## Caratteristiche + +1. **Supporto Markdown** 📝: Usa la sintassi Markdown familiare per creare mappe mentali +2. **Esperienza Interattiva** 🖱️: Supporta zoom, pan e collasso/espansione dei nodi +3. **Layout Automatico** 🔄: Calcola automaticamente posizioni e collegamenti dei nodi, senza layout manuale +4. **Design Responsivo** 📱: Si adatta automaticamente alle dimensioni del contenitore +5. **Leggero** ⚡: Caricamento veloce, prestazioni eccellenti + +## Quando Usare + +- Quando devi mostrare informazioni con struttura gerarchica 📊 +- Quando devi visualizzare piani di progetto o strutture organizzative 🏢 +- Quando devi mostrare sistemi di conoscenza o relazioni concettuali 🧠 +- Quando devi convertire documenti Markdown in mappe mentali 📄 +- Quando devi incorporare mappe mentali interattive in conversazioni o documenti 💬 + +Il componente MagicMarkmap rende la creazione e la visualizzazione delle mappe mentali semplice ed efficiente, ed è la scelta ideale per mostrare informazioni strutturate. ✨ + +--- + +## Testo Originale (Inglese) + # MagicMarkmap 魔法思维导图组件 `MagicMarkmap` 是一个用于渲染和展示思维导图的组件，基于 Markmap 库实现，支持将 Markdown 格式的文本转换为交互式思维导图。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicMarpit/README.md b/frontend/magic-web/src/opensource/components/base/MagicMarpit/README.md index 263548193..f15332985 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicMarpit/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicMarpit/README.md @@ -1,3 +1,104 @@ +# MagicMarpit 🪄 Componente Magico per Presentazioni + +MagicMarpit è un componente di rendering per presentazioni basato su Marpit e Reveal.js, utilizzato per convertire contenuti in formato Markdown in presentazioni interattive. Questo componente supporta ricche funzionalità di presentazione, come animazioni di transizione, impostazioni di tema e altro. ✨ + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------ | ------------------ | -------------------------------- | +| content | string | - | Contenuto della presentazione in formato Markdown | + +## Uso Base + +```tsx +import MagicMarpit from "@/components/base/MagicMarpit" + +// Uso base +const slideContent = ` +--- +theme: default +--- + +# Prima Slide +Questo è il contenuto della prima slide + +--- + +# Seconda Slide +- Elemento 1 +- Elemento 2 +- Elemento 3 + +--- + +# Grazie per l'attenzione +` + +; +``` + +## Sintassi Markdown + +MagicMarpit utilizza la sintassi di Marpit per definire le presentazioni: + +1. Usa `---` per separare diverse slide +2. Prima del primo `---` puoi impostare tema e stile globali +3. Supporta sintassi Markdown standard, come titoli, liste, blocchi di codice, ecc. +4. Puoi usare HTML e CSS per layout e stili più complessi + +Esempio: + +````markdown +--- +theme: default +--- + +# Titolo della Slide + +Paragrafo di contenuto + +--- + +## Esempio di Lista + +- Elemento 1 +- Elemento 2 + - Sottoelemento A + - Sottoelemento B + +--- + +## Esempio di Codice + +```javascript +function hello() { + console.log("Hello, world!") +} +``` +```` + +## Caratteristiche + +- **Supporto Markdown** 📝: Crea presentazioni con semplice sintassi Markdown +- **Presentazione Interattiva** 🎯: Esperienza di navigazione interattiva basata su Reveal.js +- **Personalizzazione Tema** 🎨: Supporta temi e stili personalizzati +- **Pulizia Automatica** 🧹: Pulisce automaticamente le risorse quando il componente viene smontato +- **Design Responsivo** 📱: Si adatta a contenitori di diverse dimensioni + +## Scenari di Uso + +- Mostrare presentazioni all'interno dell'app +- Presentazione interattiva di materiali educativi e di formazione +- Demo di prodotti e introduzioni alle funzionalità +- Presentazione di contenuti per riunioni e report +- Qualsiasi scenario che richieda la conversione di contenuti Markdown in presentazioni + +Il componente MagicMarpit offre un modo semplice e potente per trasformare contenuti testuali in presentazioni professionali, particolarmente adatto a scenari che richiedono aggiornamenti frequenti o generazione di presentazioni basata su dati. 🚀 + +--- + +## Testo Originale (Inglese) + # MagicMarpit 魔法幻灯片组件 MagicMarpit 是一个基于 Marpit 和 Reveal.js 的幻灯片渲染组件，用于将 Markdown 格式的内容转换为交互式幻灯片展示。该组件支持丰富的幻灯片功能，如切换动画、主题设置等。 @@ -72,7 +173,7 @@ theme: default ```javascript function hello() { - console.log("Hello, world!") + console.log("Hello, world!") } ``` ```` diff --git a/frontend/magic-web/src/opensource/components/base/MagicMarpit/example.md b/frontend/magic-web/src/opensource/components/base/MagicMarpit/example.md index e6fa6c815..ec35990b1 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicMarpit/example.md +++ b/frontend/magic-web/src/opensource/components/base/MagicMarpit/example.md @@ -1,3 +1,59 @@ +# Panoramica sulla situazione recente di Trump 🇺🇸 + +## Risultati elettorali 🗳️ + +- Nelle elezioni presidenziali statunitensi del 2024, Trump ha vinto + - Ha ottenuto 312 voti elettorali + - Ha sconfitto Kamala Harris (226 voti) + - Ha vinto in sette stati chiave swing (Arizona, Georgia, Michigan, ecc.) + +--- + +## Questioni legali ⚖️ + +- Affronta accuse legali complesse + - Sovvertimento dei risultati delle elezioni del 2020 + - Gestione impropria di documenti governativi riservati + - Il procuratore speciale Smith ha abbandonato alcune accuse + +--- + +## Popolarità e confronto con Harris 📊 + +- Nei sondaggi d'opinione, i due hanno livelli di supporto simili + - Harris è leggermente in vantaggio a livello nazionale + - Competizione serrata negli stati swing chiave + +--- + +## Tendenze nelle relazioni internazionali 🌍 + +- Promuove la politica "America First" + - Aumento delle tariffe sulle importazioni straniere + - Posizione dura sul conflitto Russia-Ucraina + - Sostiene la risoluzione del conflitto attraverso negoziati + +--- + +## Cambiamenti nelle proposte politiche 📜 + +- Pianifica di continuare le riduzioni fiscali e aumentare le tariffe + - Tariffe sui prodotti cinesi fino al 60% +- Insiste su una politica migratoria rigorosa + - Costruzione di una barriera al confine con il Messico + - Rimpatrio su larga scala di immigrati senza documenti +- Allentamento delle politiche ambientali e climatiche + - Supporto allo sviluppo di energie tradizionali + +--- + +# Nel complesso + +Trump continua le sue idee chiave del primo mandato, specialmente in economia e immigrazione, e mantiene l'attenzione su commercio globale e sicurezza politica. Le questioni legali rimangono una sfida importante. + +--- + +## Testo originale (in cinese) # 特朗普近期状况总览 ## 选举结果 diff --git a/frontend/magic-web/src/opensource/components/base/MagicMenu/README.md b/frontend/magic-web/src/opensource/components/base/MagicMenu/README.md index fdc8271cd..197d373c1 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicMenu/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicMenu/README.md @@ -1,3 +1,143 @@ +# MagicMenu Componente Menu Magico 🪄 + +`MagicMenu` è una versione migliorata del componente Menu di Ant Design, che offre uno stile più pulito e una migliore esperienza utente. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ---- | ------------------ | ------------------------------------ | +| ...MenuProps | - | - | Supporta tutte le proprietà del Menu di Ant Design | + +## Uso Base + +```tsx +import { MagicMenu } from '@/components/base/MagicMenu'; +import { IconHome, IconUser, IconSettings } from '@tabler/icons-react'; + +// Uso base +, + }, + { + key: 'profile', + label: 'Profilo 👤', + icon: , + }, + { + key: 'settings', + label: 'Impostazioni ⚙️', + icon: , + }, + ]} +/> + +// Elemento selezionato predefinito + + +// Menu verticale + + +// Con sottomenu + + +// Operazioni pericolose + + +// Ascolta eventi di selezione + console.log('Cliccato:', key)} + items={[ + { + key: 'home', + label: 'Home 🏠', + }, + { + key: 'profile', + label: 'Profilo 👤', + }, + ]} +/> +``` + +## Caratteristiche ✨ + +1. **Design Pulito** 🧹: Rimuove il colore di sfondo e il bordo degli elementi selezionati per un effetto visivo più pulito. +2. **Sfondo Trasparente** 🔍: Sfondo del menu trasparente per una migliore integrazione in varie interfacce. +3. **Spaziatura Ottimizzata** 📏: Spaziatura ragionevole tra gli elementi del menu per migliorare la leggibilità. +4. **Ottimizzazione Operazioni Pericolose** ⚠️: Gli elementi di operazioni pericolose hanno un effetto hover speciale per renderli più evidenti. + +## Quando Usare 📋 + +- Quando hai bisogno di fornire funzionalità di navigazione in una pagina. +- Quando devi mostrare un gruppo di operazioni o funzionalità correlate. +- Quando devi mostrare opzioni in un menu a discesa. +- Quando devi creare un menu contestuale (menu destro). + +Il componente MagicMenu rende i tuoi menu più puliti e user-friendly, mantenendo tutte le funzionalità del Menu di Ant Design. + +## Testo Originale (Cinese e Inglese) # MagicMenu 魔法菜单组件 `MagicMenu` 是一个基于 Ant Design Menu 组件的增强版菜单，提供了更简洁的样式和更好的用户体验。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicMermaid/README.md b/frontend/magic-web/src/opensource/components/base/MagicMermaid/README.md index 3a5c447df..5e6473a74 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicMermaid/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicMermaid/README.md @@ -1,3 +1,97 @@ +# MagicMermaid 📊 Componente Diagramma di Flusso Magico + +`MagicMermaid` è un componente di rendering di diagrammi basato su mermaid.js, che supporta la conversione di testo in sintassi mermaid in diagrammi visivi come diagrammi di flusso, diagrammi di sequenza, diagrammi di Gantt e altro. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------ | ------------------ | ----------------------------- | +| data | string | - | Definizione del diagramma in sintassi mermaid | + +## Uso Base + +```tsx +import { MagicMermaid } from '@/components/base/MagicMermaid'; + +// Diagramma di flusso base + B{Decisione} + B -->|Sì| C[Elaborazione] + B -->|No| D[Fine] + C --> D + `} +/> + +// Diagramma di sequenza +>PartecipanteB: Ciao, B! + PartecipanteB->>PartecipanteA: Ciao, A! + `} +/> + +// Diagramma di Gantt + + +// Diagramma di classe + + +// Diagramma di stato + Stato1 + Stato1 --> Stato2: Condizione di attivazione + Stato2 --> [*] + `} +/> +``` + +## Caratteristiche ✨ + +1. **Visualizzazione a doppia modalità** 🔄: Supporta il passaggio tra modalità diagramma e modalità codice, per una facile visualizzazione e modifica +2. **Adattamento tema** 🌙: Si adatta automaticamente ai temi chiaro/scuro, offrendo un'esperienza visiva coerente +3. **Anteprima clic** 👀: Clicca sul diagramma per un'anteprima a schermo intero, per vedere più dettagli +4. **Gestione errori** ⚠️: In caso di errori nella sintassi mermaid, mostra un messaggio di errore amichevole +5. **Esportazione SVG** 📤: Supporta l'esportazione del diagramma in formato SVG, per una facile condivisione e utilizzo + +## Quando Usare 🛠️ + +- Quando hai bisogno di visualizzare processi, relazioni o sequenze +- Quando devi incorporare diagrammi di flusso, sequenze, Gantt, ecc. nei documenti +- Quando devi convertire descrizioni testuali in rappresentazioni grafiche intuitive +- Quando devi mostrare diagrammi complessi nel contenuto Markdown +- Quando devi creare presentazioni di diagrammi interattive + +Il componente MagicMermaid rende la visualizzazione di diagrammi di flusso, relazioni e altro più intuitiva e professionale, adatto a vari scenari che richiedono visualizzazioni diagrammatiche. + +--- + +**Testo Originale (Cinese e Inglese):** + # MagicMermaid 魔法流程图组件 `MagicMermaid` 是一个基于 mermaid.js 的流程图渲染组件，支持将 mermaid 语法的文本转换为可视化的流程图、时序图、甘特图等图表。 diff --git a/frontend/magic-web/src/opensource/components/base/MagicMindmap/README.md b/frontend/magic-web/src/opensource/components/base/MagicMindmap/README.md index 7a559f7ca..c64ace8cf 100644 --- a/frontend/magic-web/src/opensource/components/base/MagicMindmap/README.md +++ b/frontend/magic-web/src/opensource/components/base/MagicMindmap/README.md @@ -1,39 +1,130 @@ +# MagicMindmap Componente Mappa Mentale Magica 🧠 + +MagicMindmap è un componente per il rendering e l'interazione operativa con mappe mentali. Questo componente è basato sulla libreria MindMap, supporta la visualizzazione delle mappe mentali, lo zoom e il layout adattivo, fornendo agli utenti un'esperienza di visualizzazione intuitiva delle mappe mentali. + +## Proprietà + +| Nome Proprietà | Tipo | Valore Predefinito | Descrizione | +| -------------- | ------- | ------------------ | ------------------------------------------------ | +| data | object | - | Struttura dati della mappa mentale, contenente nodi e informazioni di connessione | +| readonly | boolean | false | Se è in modalità sola lettura, quando true gli utenti non possono modificare la mappa mentale | + +Inoltre, il componente supporta il passaggio di altre proprietà dell'elemento HTML div. + +## Uso Base + +```tsx +import MagicMindmap from '@/components/base/MagicMindmap'; + +// Uso base +const mindmapData = { + id: 'root', + topic: 'Tema Centrale', + children: [ + { + id: 'sub1', + topic: 'Sottotema 1', + children: [ + { id: 'sub1-1', topic: 'Sottotema 1-1' }, + { id: 'sub1-2', topic: 'Sottotema 1-2' } + ] + }, + { + id: 'sub2', + topic: 'Sottotema 2', + children: [ + { id: 'sub2-1', topic: 'Sottotema 2-1' } + ] + } + ] +}; + + + +// Modalità sola lettura + + +// Stile personalizzato + +``` + +## Struttura Dati + +La struttura dati della mappa mentale segue il seguente formato: + +```typescript +interface MindMapNode { + id: string // Identificatore univoco del nodo + topic: string // Testo visualizzato del nodo + children?: MindMapNode[] // Array di nodi figli + style?: object // Stile opzionale del nodo + expanded?: boolean // Se espandere i nodi figli + // Altri attributi opzionali... +} +``` + +## Caratteristiche + +- **Operazioni Interattive** 🔄: Supporta zoom, trascinamento e espansione/compressione dei nodi +- **Layout Adattivo** 📐: Regola automaticamente la posizione dei nodi per il miglior effetto di visualizzazione +- **Design Responsivo** 📱: Si adatta ai cambiamenti delle dimensioni del contenitore, regolando automaticamente il layout della mappa mentale +- **Modalità Sola Lettura** 🔒: Supporta la modalità sola lettura, adatta per scenari di presentazione +- **Stile Personalizzato** 🎨: È possibile personalizzare l'aspetto della mappa mentale tramite CSS + +## Scenari di Uso + +- Visualizzazione della struttura della conoscenza 📚 +- Presentazione di piani di progetto e decomposizione delle attività 📋 +- Organizzazione e associazione di concetti e idee 💡 +- Presentazione strutturata dei contenuti di apprendimento 🧑‍🎓 +- Qualsiasi scenario che richieda la visualizzazione di relazioni gerarchiche e associazioni 🌐 + +Il componente MagicMindmap fornisce alle applicazioni un modo intuitivo e potente per visualizzare e operare mappe mentali, aiutando gli utenti a comprendere e organizzare meglio le strutture informative. + +--- + +## Testo Originale (Inglese) + # MagicMindmap 魔法思维导图组件 -MagicMindmap 是一个用于渲染和交互式操作思维导图的组件。该组件基于 MindMap 库实现，支持思维导图的展示、缩放和自适应布局等功能，为用户提供直观的思维导图可视化体验。 +MagicMindmap is a component for rendering and interactive operation of mind maps. This component is based on the MindMap library, supports mind map display, zooming, and adaptive layout, providing users with an intuitive mind map visualization experience. -## 属性 +## Properties -| 属性名 | 类型 | 默认值 | 描述 | -| -------- | ------- | ------ | ---------------------------------------------- | -| data | object | - | 思维导图的数据结构，包含节点和连接信息 | -| readonly | boolean | false | 是否为只读模式，为 true 时用户无法编辑思维导图 | +| Property Name | Type | Default Value | Description | +| ------------- | ------- | ------------- | ------------------------------------------------ | +| data | object | - | Mind map data structure, containing nodes and connection information | +| readonly | boolean | false | Whether it is read-only mode, when true users cannot edit the mind map | -此外，组件还支持传入其他 HTML div 元素的属性。 +Additionally, the component supports passing other HTML div element properties. -## 基本用法 +## Basic Usage ```tsx import MagicMindmap from '@/components/base/MagicMindmap'; -// 基本用法 +// Basic usage const mindmapData = { id: 'root', - topic: '中心主题', + topic: 'Central Topic', children: [ { id: 'sub1', - topic: '子主题 1', + topic: 'Subtopic 1', children: [ - { id: 'sub1-1', topic: '子主题 1-1' }, - { id: 'sub1-2', topic: '子主题 1-2' } + { id: 'sub1-1', topic: 'Subtopic 1-1' }, + { id: 'sub1-2', topic: 'Subtopic 1-2' } ] }, { id: 'sub2', - topic: '子主题 2', + topic: 'Subtopic 2', children: [ - { id: 'sub2-1', topic: '子主题 2-1' } + { id: 'sub2-1', topic: 'Subtopic 2-1' } ] } ] @@ -41,10 +132,10 @@ const mindmapData = { -// 只读模式 +// Read-only mode -// 自定义样式 +// Custom style ``` -## 数据结构 +## Data Structure -思维导图的数据结构遵循以下格式： +The mind map data structure follows the following format: ```typescript interface MindMapNode { - id: string // 节点唯一标识 - topic: string // 节点显示的文本 - children?: MindMapNode[] // 子节点数组 - style?: object // 可选的节点样式 - expanded?: boolean // 是否展开子节点 - // 其他可选属性... + id: string // Node unique identifier + topic: string // Node display text + children?: MindMapNode[] // Child node array + style?: object // Optional node style + expanded?: boolean // Whether to expand child nodes + // Other optional attributes... } ``` -## 特性 +## Features -- **交互式操作**：支持缩放、拖拽和节点展开/折叠 -- **自适应布局**：自动调整节点位置，确保最佳的可视化效果 -- **响应式设计**：适应容器大小变化，自动调整思维导图布局 -- **只读模式**：支持只读模式，适用于展示场景 -- **自定义样式**：可以通过 CSS 自定义思维导图的外观 +- **Interactive Operations**: Supports zooming, dragging, and node expansion/collapse +- **Adaptive Layout**: Automatically adjusts node positions for optimal visualization +- **Responsive Design**: Adapts to container size changes, automatically adjusting mind map layout +- **Read-Only Mode**: Supports read-only mode, suitable for presentation scenarios +- **Custom Styling**: Mind map appearance can be customized via CSS -## 使用场景 +## Use Cases -- 知识结构的可视化展示 -- 项目计划和任务分解的呈现 -- 概念和想法的组织与关联 -- 学习内容的结构化展示 -- 任何需要展示层级关系和关联的场景 +- Visualization of knowledge structures +- Presentation of project plans and task breakdowns +- Organization and association of concepts and ideas +- Structured presentation of learning content +- Any scenario requiring display of hierarchical relationships and associations -MagicMindmap 组件为应用提供了一种直观而强大的方式来展示和操作思维导图，帮助用户更好地理解和组织信息结构。 +The MagicMindmap component provides applications with an intuitive and powerful way to display and operate mind maps, helping users better understand and organize information structures.