Passer au contenu principal
Afficher en Markdown

Guide de migration

Suivez ces étapes dans l'ordre pour mettre à niveau de CLI 2.x vers V3.

1. Démarrer V3 et garder les sessions V2 accessibles

Démarrez une session V3 dans l'espace de travail que vous voulez migrer. Dans Kiro CLI 3.0.0 ou une version ultérieure, kiro-cli sans indicateur de harnais démarre aussi V3 sur une machine capable de l'exécuter et pose d'abord la question aux utilisateurs V2 existants; kiro-cli --v3 nomme le harnais et saute cette invite. Consultez Choisir un harnais d'agent pour savoir quel harnais chaque lancement démarre.

bash
kiro-cli --v3

V3 utilise un magasin de sessions différent de celui de V2. Démarrer V3 ne modifie ni ne supprime vos sessions V2 existantes.

  • Pour continuer une session V2 dans V3, utilisez /sessions, --resume ou --resume-id. Kiro crée une copie V3, conserve la session V2 originale et ne reporte pas les approbations d'outils enregistrées de la session V2. Dans Kiro CLI 3.0.0 ou une version ultérieure, --resume-id avec un ID de session V2 reste sur V2, sauf si vous transmettez aussi --v3.
  • Pour continuer une session V2 sur le harnais V2, exécutez kiro-cli chat --v2 --resume-picker.

V2 ne peut pas ouvrir une session V3.

Si vous avez besoin d'une copie externe d'une conversation importante, ouvrez-la avec le harnais qui l'a créée et exécutez /chat save <path>. Traitez le fichier exporté comme une archive, à moins d'avoir vérifié que le harnais cible peut le charger.

2. Exécuter /upgrade-agent

À partir de la session V3, exécutez la conversion et examinez ses diagnostics avant de modifier des fichiers manuellement :

> /upgrade-agent > /upgrade-agent diagnostics

La commande sauvegarde les profils sélectionnés, convertit les champs de permissions et de Hooks compatibles, et signale tout ce qui nécessite une attention manuelle. Effectuez ces étapes manuelles à partir du rapport. Exécutez /upgrade-agent de nouveau après avoir modifié les paramètres de confiance V2 pour que les règles V3 générées restent à jour. Si le menu de sélection affiche un agent désynchronisé, consultez Mise à niveau des configurations d'agent avant de le reconstruire, car cette action écrase les modifications V3 manuelles.

Réviser les Hooks migrés

/upgrade-agent convertit une carte hooks sous forme d'objet en un tableau plat de documents de Hooks. Il conserve les anciennes chaînes de déclencheurs en camelCase comme alias de compatibilité acceptés. Utilisez le PascalCase lorsque vous rédigez ou révisez manuellement les définitions migrées. Déplacez les Hooks qui doivent s'exécuter indépendamment d'un profil dans des fichiers autonomes .kiro/hooks/*.json, et mettez à jour les cinq déclencheurs de cycle de vie de la CLI :

CLI 2.xCLI V3
agentSpawnSessionStart
userPromptSubmitUserPromptSubmit
preToolUsePreToolUse
postToolUsePostToolUse
stopStop

CLI V3 prend aussi en charge PostFileCreate, PostFileSave et PostFileDelete pour les modifications de fichiers effectuées par l'agent, ainsi que PreTaskExec et PostTaskExec autour de l'exécution des tâches de spec. Les Hooks manuels sont une ancienne fonctionnalité de l'IDE 0.x. Consultez Migration des Hooks pour le schéma actuel de la CLI, le comportement des critères de correspondance, l'emplacement global des Hooks et un exemple complet avant et après.

3. Réviser les permissions converties

Examinez les règles permissions créées par /upgrade-agent, puis appliquez les changements restants ci-dessous. Résolvez chaque avertissement avant d'utiliser le profil migré dans la CI.

Pour les pipelines CI, --trust-all-tools accorde une approbation à l'échelle de la session. Pour une approbation sans interface plus étroite, --trust-tools accepte des ID d'outils V3 exacts. Vous pouvez aussi créer ~/.kiro/settings/permissions.yaml avec des règles allow propres à chaque capacité dans votre environnement CI.

Remplacements au niveau de la session conservés dans V3 :

bash
kiro-cli chat --v3 --no-interactive --trust-all-tools "Run the CI task" kiro-cli chat --v3 --no-interactive --trust-tools=read_file,grep_search "Review this repository" /tools trust-all

Dans V3, --trust-tools n'est pris en compte qu'avec --no-interactive; l'interface utilisateur interactive du terminal l'ignore. CLI 2.x accepte ses propres noms d'outils. Gardez --v3 ou --v2 dans vos scripts : une exécution sans interface qui ne nomme aucun harnais suit les valeurs par défaut indiquées sous Scripts et CI, qui dépendent des autres indicateurs que vous transmettez.

Nouvelle approche (~/.kiro/settings/permissions.yaml pour la portée utilisateur) :

yaml
rules: - capability: shell match: ["git *", "npm *", "npx *"] effect: allow - capability: fs_write match: ["src/**", "tests/**"] effect: allow - capability: fs_read effect: allow - capability: mcp match: ["my-server/*"] effect: allow

Pour la référence complète — changements de comportement, définitions de portée et tableau de conversion des motifs — consultez Migration des permissions →.

Sous-agents : dans CLI 2.x, les outils approuvés au préalable d'un sous-agent s'exécutaient sans invite, même si le parent ne les autorisait pas. Dans CLI V3, l'appel d'outil d'un sous-agent s'exécute sans invite seulement lorsque la politique de la session parente l'autorise aussi, et les exécutions sans interface refusent l'appel. Si un agent parent dépendait de ce comportement, copiez les règles allow du sous-agent dans les permissions.rules de l'agent parent, ou dans votre permissions.yaml d'utilisateur ou d'espace de travail. Consultez Autorisations des sous-agents.

4. Réviser les autres champs de configuration d'agent

/upgrade-agent conserve les champs de profil pris en charge et convertit les entrées tools et toolsSettings connues. Examinez sa sortie et ses diagnostics avant d'utiliser le profil :

  • Le champ tools utilise maintenant des balises de catégorie ou des sélecteurs directs. L'étape 6 associe les noms courants de CLI 2.x selon leur destination.
  • toolsSettings et allowedTools deviennent des permissions.rules fondées sur les capacités.
  • Les profils peuvent rester en JSON ou utiliser Markdown avec un frontmatter YAML et une requête système dans le corps.
  • Les champs comme excludedTools, includeMcpJson, includePowers, resources, permissions et welcomeMessage sont facultatifs.

Migration de toolsSettings vers permissions :

toolsSettings V2Règle permissions V3
execute_bash.allowedCommands: ["^git status$"]{ "capability": "shell", "match": ["git status"], "effect": "allow" }
execute_bash.deniedCommands: ["^rm -rf"]{ "capability": "shell", "match": ["rm -rf*"], "effect": "deny" }
execute_bash.denyByDefault: true{ "capability": "shell", "exclude": ["git *", "npm *"], "effect": "deny" }
fs_read.allowedPaths: ["src/**"]{ "capability": "fs_read", "match": ["src/**"], "effect": "allow" }
fs_read.deniedPaths: [".env"]{ "capability": "fs_read", "match": [".env"], "effect": "deny" }
fs_write.allowedPaths: ["src/**"]{ "capability": "fs_write", "match": ["src/**"], "effect": "allow" }

Remarque : les allowedCommands et deniedCommands de V2 utilisaient des motifs regex. Les permissions V3 utilisent des globs : retirez les ancres comme ^ et $, remplacez .* par *, et réécrivez les regex complexes sous forme de plusieurs règles.

Consultez la référence de configuration d'agent pour les champs actuels et les serveurs MCP intégrés, et sa section Format Markdown pour un exemple Markdown complet. Si le profil contient des Hooks, examinez leur tableau converti ou déplacez l'automatisation indépendante du profil dans un fichier autonome, comme décrit dans Migration des Hooks.

5. Remplacer l'outil AWS de CLI 2.x par un serveur MCP

L'outil AWS structuré de CLI 2.x (use_aws, alias privilégié aws) n'est pas intégré à V3. Configurez plutôt un serveur MCP AWS. L'entrée AWS MCP distante gérée du répertoire de serveurs MCP utilise cette configuration :

.kiro/settings/mcp.json :

json
{ "mcpServers": { "aws-mcp": { "url": "https://aws-mcp.us-east-1.api.aws/mcp", "disabled": false } } }

Examinez l'accès IAM du serveur avant de l'utiliser, et consultez le registre pour connaître les options de configuration actuelles.

6. Mettre à jour les références d'outils selon leur destination

V3 utilise des identifiants différents pour la sélection dans le profil d'agent, la politique de permissions et la correspondance à l'exécution. Ne substituez pas un espace de noms à un autre.

Entrées tools du profil d'agent

Le champ tools accepte des balises de catégorie et certains ID d'outils directs :

Noms CLI 2.x acceptésSélecteur V3Type de sélecteur
fs_read, fsRead, read, grep, glob, code, introspectreadBalise de catégorie
fs_write, fsWrite, writewriteBalise de catégorie
execute_bash, execute_cmd, executeCmd, shellshellBalise de catégorie
web_fetch, web_searchwebBalise de catégorie
agent_crew, use_subagent, subagentsubagentBalise de catégorie
knowledgeknowledgeID d'outil direct

/upgrade-agent réécrit les noms de liste de tâches de CLI 2.x (task, todo, todo_list) en todo_list, mais CLI V3 n'a pas d'outil de liste de tâches; cette entrée ne sélectionne donc rien. Retirez-la du profil converti.

Règles de permissions

Le champ capability utilise des classes d'opérations, et non des balises de profil ou des ID d'outils :

Famille d'outils CLI 2.xCapacité de permission V3
fs_read, fsRead, read, grep, glob, code, introspectfs_read
fs_write, fsWrite, writefs_write
execute_bash, execute_cmd, executeCmd, shellshell
web_fetchweb_fetch
web_searchweb_search
agent_crew, use_subagent, subagentsubagent

knowledge n'a aucune correspondance de capacité par outil générée. Définissez des règles pour les opérations que le workflow effectue réellement au lieu d'inventer un nom de capacité.

Critères de correspondance des Hooks et références d'exécution sérialisées

Les critères de correspondance PreToolUse et PostToolUse de V3 acceptent un sélecteur d'outil (un ID d'outil V3, une balise de catégorie, @builtin, @mcp, @<server>, @<server>/<tool> ou un caractère générique */?) ou une expression régulière. Un critère de correspondance qui contient des métacaractères regex est évalué uniquement comme une regex non ancrée par rapport à l'ID d'outil interne. /upgrade-agent réécrit les noms CLI 2.x connus vers la balise correspondante; utilisez ce tableau lorsque vous rédigez un critère de correspondance manuellement :

Critère de correspondance CLI 2.xCritère de correspondance de Hook V3
fs_read, fsRead, readread (balise; couvre aussi grep_search, file_search, code, introspect) ou ^(read_file|list_directory)$
grepgrep_search
globfile_search
fs_write, fsWrite, writewrite (balise) ou ^(fs_write|fs_append|str_replace|delete_file)$
execute_bash, execute_cmd, executeCmd, shellshell (balise) ou execute_bash (correspond aussi à execute_pwsh)
web_fetchweb_fetch
web_searchremote_web_search
codecode
introspectintrospect
use_aws, awsAucun outil intégré V3; faites correspondre l'outil MCP configuré avec @<server>/<tool> ou son ID interne mcp_<server>_<tool>

L'indicateur sans interface --trust-tools accepte une liste d'ID d'outils V3 séparés par des virgules — par exemple, --trust-tools=read_file,grep_search — et, dans Kiro CLI 3.3.0 ou version ultérieure, aussi des noms d'outils V2, des références @server et des motifs */?, mais jamais des regex (consultez le mode sans interface). Consultez le catalogue d'outils pour les balises de profil et les ID intégrés, Permissions pour les capacités et Types de Hooks pour le comportement des critères de correspondance.

7. Valider votre migration

  1. À partir de votre shell, validez chaque configuration d'agent migrée :

    bash
    kiro-cli agent validate --path .kiro/agents/my-agent.json
  2. Démarrez ou revenez à une session V3 dans l'espace de travail migré. Exécutez /config et /hooks pour confirmer que Kiro a chargé les agents, les permissions et les Hooks attendus.

  3. Exécutez des commandes représentatives pour vérifier le comportement d'approbation que vous visiez.

Résolvez chaque avertissement de conversion ou erreur de validation avant d'utiliser la configuration dans la CI.

Prochaines étapes

  • Migration des permissions — conseils détaillés sur la migration des indicateurs de confiance vers permissions.yaml
  • Migration des Hooks — correspondance complète des déclencheurs et référence du nouveau format
Page mise à jour : 12 novembre 2026