Tutoriel de démarrage ZCode

ZCode est un environnement de développement pour agents développeurs lancé par Zhipu, également appelé Agentic Development Environment, abrégé en ADE. Contrairement aux éditeurs traditionnels, il est doté d’un assistant IA capable d’intervenir en profondeur sur les projets, de visualiser les projets, de modifier des fichiers, d’exécuter des commandes et d’organiser les modifications de code.

ZCode peut connecter des agents IA à de vrais projets, en accomplissant au même endroit l’ensemble du flux de développement : analyse des besoins, modification du code, tests, revue de code et vérifications avant lancement.

Les outils d’IA ordinaires ne peuvent générer que des extraits de code dispersés. ZCode permet de confier des tâches de développement complètes en langage naturel, ce qui le rend adapté aux utilisateurs qui souhaitent piloter le développement en langage naturel.

Le cœur de ZCode n’est pas une simple conversation, mais l’avancement continu d’une tâche complète autour d’un objectif de développement.

Concept Description Scénarios adaptés
ZCode Un environnement de développement pour les agents IA. Pour ceux qui veulent utiliser le langage naturel pour faire avancer le développement de vrais projets.
ZCode Agent L’agent chargé de comprendre les tâches, de lire le contexte, de modifier le code et de vérifier les résultats. Décomposition de besoins complexes, génération de code, débogage, tests.
Tâche à long terme Tâches de développement qui s'étendent sur une longue période et impliquent de nombreuses étapes. Refactoriser des modules, corriger des bugs complexes, implémenter des fonctionnalités complètes.
Espace de travail L'endroit où ZCode gère les fichiers de projet, le terminal, l'état Git et le contexte des tâches. Ouvrez un projet existant ou créez un nouveau projet dans un répertoire.

Ce pour quoi ZCode est adapté

ZCode convient aux travaux de développement qui nécessitent un contexte continu. Il peut lire des fichiers, comprendre la structure d'un projet, exécuter des commandes et fournir un résumé une fois les modifications terminées.

Ce type de capacité convient à l'ingénierie réelle, pas seulement à des questions-réponses ponctuelles.

Type de tâche Ce que vous pouvez demander à ZCode de faire Exemple de prompt
Développement de nouvelles fonctionnalités Vérifiez la structure du projet en fonction des exigences, créez ou modifiez les fichiers associés. Aidez-moi à ajouter une page de connexion à ce projet et à l'intégrer au routage existant.
Correction de bug Localisez la cause de l'erreur, modifiez le code et exécutez les commandes de vérification. Corrigez le problème où la page scintille après avoir cliqué sur un bouton sur mobile.
Compréhension du code Démêlez les relations entre modules et expliquez la chaîne d'appel d'une fonctionnalité, depuis l'entrée jusqu'à l'implémentation. Aidez-moi à expliquer comment fonctionne le flux de paiement de ce projet.
Revue de code Vérifiez les risques de changement, fournissez des suggestions en ligne ou des pistes d'amélioration. Veuillez examiner les modifications actuelles, en vous concentrant sur les risques de régression.
Préparation de la version Générez le journal des modifications, organisez les notes de version, vérifiez l'état de Git. Générez un brouillon de note de version à partir des commits récents.

Installation de ZCode

Après être entré sur le site officiel chinois de ZCode, vous pouvez cliquer sur l'entrée de téléchargement sur la page d'accueil.

L'adresse du site officiel esthttps://zcode.z.ai/cn。

La page du site officiel affiche les versions téléchargeables actuellement disponibles, compatibles avec Windows, macOS et Linux. Habituellement, le site officiel affiche le bouton de téléchargement pour le système actuel :

Après le téléchargement, cliquez simplement pour installer :

Préparation de base après l'installation

Au premier lancement, vous accédez à la page « Configuration du premier lancement ». Après l'avoir terminée, cliquez sur « Se connecter et utiliser » dans le coin inférieur gauche pour aller à la page de connexion :

Si vous souhaitez utiliser les services de modèle, vous devez également effectuer la configuration liée à la clé API ou auCoding Plan. Vous pouvez aussi vous connecter, puis la configurer sur la page des paramètres :

Le quota gratuit officiel est actuellement très limité et pratiquement insuffisant. Nous recommandons les forfaits Coding Plan suivants :

Ensuite, prenonsle Coding Plan de ByteDance Arkcomme exemple de configuration. Visitez ArkÉvénement Coding Plan, abonnez-vous à un forfait selon vos besoins. Si l'utilisation est faible, la version Lite suffit ; si l'utilisation est très élevée, vous pouvez utiliser la version Pro.

Après un achat réussi, cliquez surCréer votre clé API：

Cliquez ensuite sur le bouton Créer :

Cliquez sur la petite icône en forme d'œil ci-dessous pour voir la clé API. Si nécessaire, copiez-la :

Les différents outils ont différentes configurations d'URL de base selon le protocole compatible :

  • Outils compatibles avec le protocole API Anthropic :https://ark.cn-beijing.volces.com/api/coding
  • Outils compatibles avec le protocole API OpenAI :https://ark.cn-beijing.volces.com/api/coding/v3

Ici, nous choisissonshttps://ark.cn-beijing.volces.com/api/coding, définissez la clé API sur la vôtre. La liste des modèles permet d'ajouter plusieurs modèles. Ici, saisissezKimi-K2.6, vous pouvez également ajouter d'autres modèles tels queDeepSeek-V4-Pro：

Après l'ajout, vous pouvez tester si le modèle est disponible :

Vous pouvez voir le modèle ajouté dans le coin inférieur droit de la boîte de dialogue sur la page d'accueil :

ZCode propose des pages pour la configuration de la clé API, les statistiques d'utilisation, les retours utilisateurs et l'assistance.

Utiliser ZCode pour la première fois

Nous pouvons commencer par un projet simple, en demandant à ZCode de créer un mini-jeu pour navigateur, ou en lui demandant d'expliquer la structure de répertoires d'un projet existant.

Cela vous aide à comprendre rapidement le fonctionnement de ZCode.

Ouvrir ou créer un espace de travail

Un espace de travail peut être compris comme le répertoire de projet que ZCode traite actuellement.

Vous pouvez ouvrir un répertoire de projet existant ou démarrer un nouveau projet dans un répertoire vide.

ZCode lira les fichiers, exécutera les commandes et gérera les modifications dans ce répertoire.

Création d'une nouvelle tâche

Dans ZCode, une tâche est l'unité de base qui pilote le travail de l'agent.

Les exemples du site officiel montrent comment décrire des tâches en langage naturel.

La page affiche également le raccourci de nouvelle tâche.⌘N。

Exemple de création d'une nouvelle tâche :

Create a smart Gomoku web game, including a game board, player moves, win/loss detection, and a simple computer opponent.

Observer le processus d'exécution

Une fois qu'une tâche démarre, ZCode analyse le projet en fonction de l'objectif et procède étape par étape.

Vous pouvez voir la progression de la tâche, les journaux d'exécution, les modifications de fichiers, la sortie du terminal et l'état Git.

C'est plus fiable que de simplement copier un morceau de code généré par IA, car il peut remettre le code dans le projet réel pour vérification.

Zone d'interface Objectif Ce à quoi les débutants doivent prêter attention
Progression de la tâche Affiche la décomposition et l'état d'achèvement de la tâche en cours. Confirmez si l'agent progresse conformément à l'objectif.
Sortie du terminal Affiche les résultats de l'exécution des commandes. Surveillez les erreurs et si les commandes de vérification réussissent.
Modifications de fichiers Affiche les fichiers qui ont été ajoutés, modifiés ou supprimés. Vérifiez si les modifications correspondent aux attentes.
État Git Affiche l'état du contrôle de version de l'espace de travail actuel. Avant de valider, confirmez qu'il ne contient que les modifications dont vous avez besoin.

Un exemple complet pour débutant

Ci-dessous, nous utilisons un projet front-end simple pour démontrer comment assigner des tâches à ZCode.

Cet exemple ne dépend pas d'un backend, ce qui le rend adapté aux débutants pour comprendre le processus.

Exemple

Veuillez m'aider à créer un projet simple de compteur de page web.

Exigences :
1. Utilisez trois fichiers : HTML, CSS et JavaScript.
2. Affichez la valeur actuelle du compteur sur la page.
3. Fournissez trois boutons : « Ajouter un », « Soustraire un » et « Réinitialiser ».
4. Gardez un style simple et adapté aux débutants pour la lecture.
5. Après avoir terminé, veuillez exécuter les vérifications nécessaires et me dire quels fichiers ont été créés.

Ce prompt indique clairement à ZCode quoi créer, quels fichiers utiliser, quelles fonctionnalités inclure, et que les résultats doivent être signalés après la fin.

Plus le prompt est spécifique, plus l'exécution de l'Agent a de chances de correspondre aux attentes.

Ensuite, une invite de permission apparaîtra ; accordez la permission et cliquez sur confirmer :

Structure possible du projet généré

Si vous exécutez cette tâche dans un répertoire vide, ZCode peut créer une structure de fichiers similaire à celle ci-dessous.

counter-demo/
├── index.html
├── styles.css
└── app.js

Vous pouvez consulter le code source :

Effet d'affichage du code source :

Comment écrire de bons prompts pour ZCode

ZCode peut comprendre le langage naturel, mais cela ne signifie pas que des prompts plus courts sont toujours meilleurs.

Un bon prompt doit inclure l'objectif, la portée, les contraintes et les critères d'acceptation.

Cela permet à l'Agent de planifier et d'exécuter de manière plus fiable.

Composant Description Exemple
Objectif Décrivez ce que vous voulez accomplir au final. Ajoutez une page de paramètres utilisateur.
Portée Précisez quelles parties doivent être modifiées et lesquelles ne doivent pas l'être. Modifiez uniquement la page frontend, ne modifiez pas les API backend.
Contraintes Précisez la stack technique, le style et les exigences de compatibilité. Utilisez la bibliothèque de composants existante, n'ajoutez pas de nouvelles dépendances.
Critères d'acceptation Expliquez comment déterminer la réussite après l'achèvement. L'exécution de npm test réussit, et la mise en page fonctionne correctement sur mobile.

Exemple

Veuillez m'aider à corriger le problème où le bouton de la page de connexion est masqué sur mobile.

Portée :
- Ne modifiez que les fichiers liés à la page de connexion.
- Ne modifiez pas les API backend.
- N'ajoutez pas de dépendances tierces.

Exigences :
- Conservez le style visuel existant.
- Adaptez-vous aux écrans mobiles d'une largeur de 375px.
- Après modification, veuillez expliquer quels fichiers ont été modifiés.
- Si le projet dispose de commandes de test ou de vérification, veuillez les exécuter et rapporter les résultats.

N'écrivez pas simplement "aidez-moi à l'optimiser." Ce type de prompt a une portée trop large, et l'Agent aura du mal à déterminer ce que vous voulez vraiment.

Flux de travail courants

L'avantage de ZCode réside dans l'articulation du processus de développement.

Vous pouvez mener une tâche de la description des exigences à la modification du code, puis à la validation et au résumé.

Créer une fonctionnalité à partir de zéro

Lorsque vous souhaitez créer une nouvelle fonctionnalité, commencez par clarifier les limites de cette fonctionnalité.

Si le projet dispose déjà d'une stack technique, demandez également à ZCode de respecter les conventions existantes.

Exemple

Veuillez ajouter une page "À propos" au projet actuel.

Exigences :
- Utilisez l'approche de routage existante du projet.
- Réutilisez les composants de mise en page existants.
- La page comprend trois sections : titre, introduction et informations de contact.
- N'ajoutez pas de nouvelles dépendances.
- Une fois terminé, veuillez lister les fichiers ajoutés et modifiés.

Comprendre le code existant

Lorsque vous reprenez un projet que vous ne connaissez pas, vous pouvez d'abord demander à ZCode d'expliquer la structure plutôt que de modifier immédiatement le code.

Cela aide à réduire le risque d'apporter des modifications involontaires.

Exemple

Veuillez ne modifier aucun fichier pour le moment.

Aidez-moi à lire la structure actuelle du projet et à expliquer :
- Où se trouve le point d'entrée de l'application.
- Où les routes sont définies.
- Où les requêtes API sont encapsulées.
- Quelles sont les commandes de build et de test, respectivement.

Vérifications avant commit

Avant de committer du code, vous pouvez demander à ZCode de passer en revue les modifications actuelles.

Cela peut vous aider à identifier les fichiers manquants, les régressions potentielles et les tests manquants.

Exemple

Veuillez examiner les modifications dans l’espace de travail actuel.

Concentrez-vous sur la vérification :
- S’il y a des bugs évidents.
- Si les fonctionnalités existantes sont cassées.
- S’il y a des variables inutilisées ou du code de débogage.
- Si des tests supplémentaires sont nécessaires.

Veuillez d’abord fournir une liste de problèmes ; ne modifiez pas directement les fichiers.

Confirmation de sécurité et autorisations

ZCode entre dans un flux de confirmation avant les commandes critiques, les modifications de fichiers et les opérations à privilèges élevés. Cela empêche l’Agent d’exécuter des opérations dangereuses à votre insu.

Vous pouvez lire les détails de la confirmation avant d’exécuter une commande, puis décider de l’autoriser ou non.

Type d’opération Pourquoi la confirmation est nécessaire Pratique recommandée
Modifier des fichiers Va modifier le code du projet. Confirmez si le chemin du fichier et la cible de modification sont corrects.
Supprimer des fichiers Peut entraîner une perte de données. Vérifiez le contenu du fichier avant la suppression, et sauvegardez-le si nécessaire.
Exécuter des commandes Les commandes peuvent installer des dépendances, démarrer des services ou modifier l'environnement. Confirmez l'objectif de la commande et évitez d'exécuter des commandes inconnues à haut risque.
Opérations Git Peut affecter l'historique des commits ou le dépôt distant. Vérifiez git status avant de faire un commit et un push.

Si vous n'êtes pas certain qu'une commande soit sans risque, vous pouvez d'abord demander à ZCode d'expliquer le but de la commande plutôt que de la laisser s'exécuter directement.

Commandes courantes et méthodes d'inspection

ZCode peut utiliser le terminal pour exécuter les commandes du projet.

Les commandes spécifiques dépendent de la stack technique de votre projet.

Voici quelques commandes qui apparaissent dans les exemples officiels et les scénarios de développement courants.

Commande Fonction Exemple
pwd Afficher le répertoire courant. Confirmer si le terminal actuel de ZCode se trouve dans le répertoire du projet.
git status --short Afficher les modifications Git dans un format concis. Confirmer quels fichiers ont été modifiés avant de faire un commit.
node --check app.js Vérifier la syntaxe du fichier JavaScript. Vérifier si app.js contient des erreurs de syntaxe.
npm test Exécuter les tests du projet. Adapté aux projets JavaScript ou frontend.
npm run build Lancer la compilation du projet. Confirmer que le projet peut être empaqueté correctement avant la publication. 
$ git status --short
 M src/App.js
 M src/styles.css

La sortie ci-dessus indique que deux fichiers ont été modifiés.

Avant de commiter, vous devez confirmer que ces modifications correspondent toutes aux attentes.

Aperçu des capacités avancées

En plus de l'exécution de tâches sur ordinateur, la documentation ZCode mentionne également certaines capacités avancées.

Vous n'avez pas besoin de toutes les maîtriser d'un coup au stade débutant, mais vous pouvez d'abord comprendre quels problèmes elles résolvent.

Capacité Description Quand l'utiliser
Contrôle à distance Suivre ou contrôler à distance des tâches d'Agent. Lorsqu'une tâche prend beaucoup de temps et que vous souhaitez continuer à vérifier sa progression après avoir quitté votre ordinateur.
Canal Bot Déclencher et faire progresser les tâches via un bot Feishu ou WeChat. Collaboration en équipe, suivi de l'avancement sur mobile et instructions complémentaires à distance.
Compétence Fournir des capacités ou des workflows spécialisés pour des tâches spécifiques. Lorsque vous traitez de façon répétée des tâches similaires, comme des audits de sécurité, la génération de documentation ou des exécutions de tests.
Serveurs MCP Connecter des outils externes ou des sources de données à l'Agent. Lorsque vous devez connecter une base de données, une base de connaissances, un système interne ou des outils spécialisés.
Sous-agents Laisser différents Agents gérer différentes sous-tâches. Lorsqu'une tâche importante nécessite une exploration parallèle, une révision ou une division du travail.

Questions fréquentes des débutants

Voici quelques problèmes courants que vous pouvez rencontrer lorsque vous commencez à utiliser ZCode.

ZCode modifiera-t-il automatiquement mon projet sans autorisation ?

Les opérations critiques de ZCode passent par un flux de confirmation.

Vous devez vérifier les fichiers qu'il va modifier et les commandes qu'il va exécuter avant de les autoriser.

Si vous voulez seulement qu'il lise le projet, vous pouvez écrire explicitement "ne pas modifier les fichiers" dans l'invite.

Dois-je laisser ZCode faire plusieurs choses à la fois ?

Il n'est pas recommandé aux débutants de confier des tâches trop importantes dès le départ.

Une meilleure approche consiste à décomposer la tâche en plus petits morceaux.

Par exemple, demandez-lui d'abord de comprendre la structure du projet, puis de modifier un module, et enfin d'exécuter la validation.

Que faire si une tâche échoue

Vérifiez d'abord la sortie du terminal et les messages d'erreur.

Demandez ensuite à ZCode de continuer à corriger en fonction des erreurs.

Ne vous précipitez pas pour commencer une tâche complètement différente, sinon vous risquez de perdre le contexte.

Quand une revue manuelle est-elle nécessaire ?

Lorsque la logique métier, les autorisations, la sécurité, les paiements, la suppression de données ou les opérations de publication sont concernés, une vérification manuelle doit être effectuée.

L'IA peut aider à identifier les problèmes, mais la responsabilité finale incombe toujours au développeur.

Suggestions d'apprentissage

La meilleure façon d'apprendre ZCode n'est pas de mémoriser des commandes, mais de s'exercer en commençant par de petites tâches.

Vous pouvez d'abord l'utiliser pour créer une page simple, puis lui demander d'expliquer le code généré.

Ensuite, essayez de lui demander de corriger un petit bug et observez comment il lit les fichiers, modifie le code et valide les résultats.

Une fois que vous êtes familier avec cette approche de développement pilotée par les tâches, utilisez progressivement des capacités telles que la revue de code, la préparation de publication, Remote Control et Skill.

Considérez ZCode comme un partenaire de développement capable d'intervenir sur des projets, plutôt qu'un chatbot qui ne fait que répondre à des questions. Il est ainsi plus facile de tirer parti de sa valeur.

Autres extensions