AnkiConnect

Aperçu

Activez une interaction fiable avec Anki via l'API HTTP locale AnkiConnect. Utilisez cette compétence pour traduire les demandes de l'utilisateur en actions AnkiConnect, composer des requêtes JSON, les exécuter via curl/jq (ou des outils équivalents) et interpréter les résultats de manière sûre.

Préconditions et environnement

• Si Anki n'est pas en cours d'exécution, lancez Anki, puis attendez que le serveur AnkiConnect réponde à l'adresse http://127.0.0.1:8765 (par défaut). Vérifiez la disponibilité à l'aide de curl, par exemple curl -sS http://127.0.0.1:8765 devrait retourner Anki-Connect.

Politique de sécurité et de confirmation (critique)

CRITIQUE — AUCUNE EXCEPTION

Avant toute opération destructrice ou modifiante sur les notes ou les cartes (ajout, mise à jour, suppression, reprogrammation, suspension, réactivation, changement de deck ou modification des champs/tags), demandez une confirmation à l'utilisateur. Utilisez l'outil AskUserQuestion s'il est disponible ; sinon demandez via le chat. Demandez la confirmation une seule fois par opération logique, même si elle nécessite plusieurs appels API (par ex. recherche + mise à jour + vérification). Groupez la confirmation par intention et scope (par ex. « Mettre à jour 125 notes correspondant à la requête X »).

Considérez les éléments suivants comme nécessitant une confirmation par défaut :

• Notes : addNote, addNotes, updateNoteFields, updateNoteTags, updateNote, updateNoteModel, deleteNotes, removeEmptyNotes, replaceTags, replaceTagsInAllNotes, clearUnusedTags.
• Cartes : setEaseFactors, setSpecificValueOfCard, suspend, unsuspend, forgetCards, relearnCards, answerCards, setDueDate, changeDeck.
• Modifications de deck ou de modèle qui changent matériellement les cartes/notes (suppression de deck, modifications de modèle). Demandez une confirmation même si l'action n'est pas explicitement listée ci-dessus.

Fondamentaux de l'API

Format des requêtes

Toute requête est du JSON avec :

• action : nom de l'action sous forme de chaîne
• version : version de l'API (utilisez 6 sauf si l'utilisateur spécifie autrement)
• params : objet de paramètres (optionnel)

Format des réponses

Toute réponse est du JSON avec :

• result : valeur retournée
• error : null en cas de succès ou une chaîne décrivant l'erreur

Vérifiez toujours error avant d'utiliser result.

Permissions

• Utilisez requestPermission en premier lors d'une interaction depuis une origine non fiable ; c'est la seule action qui accepte n'importe quelle origine.
• Utilisez version pour assurer la compatibilité ; les versions antérieures peuvent omettre le champ error dans les réponses quand version ≤ 4.

Modèles curl + jq

Préférez jq pour construire du JSON et analyser les réponses. Gardez les requêtes explicites et structurées.

Modèle de requête minimal

jq -n --arg action "deckNames" --argjson version 6 '{action:$action, version:$version}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-

Avec paramètres

jq -n \
    --arg action "findNotes" \
    --argjson version 6 \
    --arg query "deck:French tag:verbs" \
    '{action:$action, version:$version, params:{query:$query}}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-

Gestion de result/error

curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @- \
| jq -e 'if .error then halt_error(1) else .result end'

Regroupement de plusieurs actions

Utilisez multi pour réduire les allers-retours et grouper les actions sous une seule confirmation lors de la modification de données.

jq -n --argjson version 6 --arg query "deck:French" \
    '{action:"multi", version:$version, params:{actions:[
        {action:"findNotes", params:{query:$query}},
        {action:"notesInfo", params:{notes:[]}} 
    ]}}' \
| curl -sS http://127.0.0.1:8765 -X POST -H 'Content-Type: application/json' -d @-

Remplacez le tableau vide par le résultat de l'action précédente lors du chaînage ; dans l'utilisation en CLI, divisez en deux appels sauf si vous utilisez un langage de script.

Orientation du flux de travail principal

1) Vérifier la connectivité et la version

• Appelez requestPermission (sûr).
• Appelez version pour confirmer le niveau de l'API et utilisez version: 6 dans les requêtes.

2) Découvrir les actions supportées

• Utilisez apiReflect avec scopes: ["actions"] pour lister les actions supportées.
• Utilisez cette liste pour mapper l'intention de l'utilisateur aux noms d'actions.

3) Résoudre la demande de l'utilisateur en séquence d'actions

• Identifiez les opérations en lecture seule par rapport aux opérations destructrices.
• Pour les opérations destructrices/modifiantes sur les notes/cartes, demandez une confirmation une fois avec le scope et le nombre.
• Préférez findNotes/findCards + notesInfo/cardsInfo pour les aperçus avant modification.

4) Exécuter et valider

• Exécutez les appels dans l'ordre.
• Vérifiez error pour chaque réponse.
• Rapportez les résultats résumés et tous les ID retournés.

Recettes de tâches courantes (orientées CLI)

Lister les decks

• Action : deckNames

Créer un deck

• Action : createDeck
• Confirmation requise si le deck est créé dans le cadre d'un flux de modification de cartes/notes.

Chercher des notes / cartes

• Actions : findNotes, findCards
• Utilisez la syntaxe de recherche Anki (voir « Notes rapides sur la syntaxe de recherche » ci-dessous).

Aperçu des données de note

• Action : notesInfo (IDs de note)

Ajouter des notes

• Actions : addNote, addNotes
• Confirmation requise.
• Utilisez canAddNotes ou canAddNotesWithErrorDetail pour les vérifications préalables.

Mettre à jour les champs ou les tags de note

• Actions : updateNoteFields, updateNoteTags, ou updateNote combinée
• Confirmation requise.
• Attention : N'ouvrez pas la note dans le navigateur ; les mises à jour risquent de ne pas s'appliquer.

Supprimer des notes

• Action : deleteNotes
• Confirmation requise.

Suspendre/réactiver des cartes

• Actions : suspend, unsuspend
• Confirmation requise.

Déplacer des cartes vers un deck

• Action : changeDeck
• Confirmation requise.

Définir la date d'échéance ou reprogrammer

• Action : setDueDate
• Confirmation requise.

Téléchargement/téléchargement de médias

• Actions : storeMediaFile, retrieveMediaFile, getMediaFilesNames, getMediaDirPath, deleteMediaFile
• Utilisez base64 (data), chemin de fichier (path) ou URL (url) pour le téléchargement.

Synchroniser

• Action : sync

Notes rapides sur la syntaxe de recherche (pour findNotes/findCards)

• Séparez les termes par des espaces ; les termes sont ANDés par défaut.
• Utilisez or, parenthèses et - pour la logique NOT.
• Utilisez deck:Name, tag:tagname, note:ModelName, card:CardName.
• Utilisez front:... ou d'autres noms de champs pour limiter par champ.
• Utilisez re: pour les regex, w: pour les recherches avec limite de mot, nc: pour ignorer les accents.
• Utilisez is:due, is:new, is:learn, is:review, is:suspended, is:buried pour filtrer les états des cartes.
• Utilisez les recherches prop: pour les propriétés comme l'intervalle ou la date d'échéance.
• Échappez les caractères spéciaux avec des guillemets ou des barres obliques selon les besoins.

Catalogue des actions (à utiliser comme référence de mapping)

Actions sur les cartes

• getEaseFactors
• setEaseFactors
• setSpecificValueOfCard
• suspend
• unsuspend
• suspended
• areSuspended
• areDue
• getIntervals
• findCards
• cardsToNotes
• cardsModTime
• cardsInfo
• forgetCards
• relearnCards
• answerCards
• setDueDate

Actions sur les decks

• deckNames
• deckNamesAndIds
• getDecks
• createDeck
• changeDeck
• deleteDecks
• getDeckConfig
• saveDeckConfig
• setDeckConfigId
• cloneDeckConfigId
• removeDeckConfigId
• getDeckStats

Actions graphiques

• guiBrowse
• guiSelectCard
• guiSelectedNotes
• guiAddCards
• guiEditNote
• guiAddNoteSetData
• guiCurrentCard
• guiStartCardTimer
• guiShowQuestion
• guiShowAnswer
• guiAnswerCard
• guiUndo
• guiDeckOverview
• guiDeckBrowser
• guiDeckReview
• guiImportFile
• guiExitAnki
• guiCheckDatabase
• guiPlayAudio

Actions médias

• storeMediaFile
• retrieveMediaFile
• getMediaFilesNames
• getMediaDirPath
• deleteMediaFile

Actions diverses

• requestPermission
• version
• apiReflect
• sync
• getProfiles
• getActiveProfile
• loadProfile
• multi
• exportPackage
• importPackage
• reloadCollection

Actions sur les modèles

• modelNames
• modelNamesAndIds
• findModelsById
• findModelsByName
• modelFieldNames
• modelFieldDescriptions
• modelFieldFonts
• modelFieldsOnTemplates
• createModel
• modelTemplates
• modelStyling
• updateModelTemplates
• updateModelStyling
• findAndReplaceInModels
• modelTemplateRename
• modelTemplateReposition
• modelTemplateAdd
• modelTemplateRemove
• modelFieldRename
• modelFieldReposition
• modelFieldAdd
• modelFieldRemove
• modelFieldSetFont
• modelFieldSetFontSize
• modelFieldSetDescription

Actions sur les notes

• addNote
• addNotes
• canAddNotes
• canAddNotesWithErrorDetail
• updateNoteFields
• updateNote
• updateNoteModel
• updateNoteTags
• getNoteTags
• addTags
• removeTags
• getTags
• clearUnusedTags
• replaceTags
• replaceTagsInAllNotes
• findNotes
• notesInfo
• notesModTime
• deleteNotes
• removeEmptyNotes

Actions statistiques

• getNumCardsReviewedToday
• getNumCardsReviewedByDay
• getCollectionStatsHTML
• cardReviews
• getReviewsOfCards
• getLatestReviewID
• insertReviews

Notes et pièges

• Gardez Anki au premier plan sur macOS ou désactivez App Nap pour empêcher AnkiConnect de se mettre en pause.
• Lors de la mise à jour d'une note, assurez-vous qu'elle n'est pas consultée dans l'éditeur du navigateur ; les mises à jour risquent de ne pas s'appliquer.
• Les chemins importPackage sont relatifs au dossier collection.media d'Anki, non au client.
• deleteDecks nécessite cardsToo: true pour supprimer les cartes en même temps que les decks.

Ressources

Aucun script ou ressource fourni n'est nécessaire pour cette compétence.