AnkiConnect

概要

AnkiConnect ローカル HTTP API を通じて Anki との信頼できる対話を実現します。このスキルを使用して、ユーザーリクエストを AnkiConnect アクションに変換し、JSON リクエストを作成し、curl/jq（または同等のツール）で実行し、結果を安全に解釈します。

前提条件と環境

• Anki が実行されていない場合は Anki を起動し、AnkiConnect サーバーが http://127.0.0.1:8765（デフォルト）で応答するまで待機します。curl を使用した確認（例：curl -sS http://127.0.0.1:8765 は Anki-Connect を返すべき）で準備状況を確認します。

安全確認ポリシー（重要）

重要 — 例外なし

ノートまたはカードに対する破壊的または変更操作（追加、更新、削除、リスケジューリング、サスペンド、サスペンド解除、デッキ変更、フィールド/タグ変更）を実行する前に、ユーザーから確認をリクエストします。AskUserQuestion ツールが利用可能な場合はそれを使用し、そうでない場合はチャットで質問します。論理的な操作ごとに1 回だけ確認をリクエストしてください。複数の API 呼び出しが必要な場合でも（例：検索 + 更新 + 検証）変わりません。意図と範囲でグループ化された確認をリクエストしてください（例：「クエリ X にマッチする 125 個のノートを更新」）。

デフォルトで確認が必要と見なされるのは以下の場合です：

• ノート：addNote、addNotes、updateNoteFields、updateNoteTags、updateNote、updateNoteModel、deleteNotes、removeEmptyNotes、replaceTags、replaceTagsInAllNotes、clearUnusedTags。
• カード：setEaseFactors、setSpecificValueOfCard、suspend、unsuspend、forgetCards、relearnCards、answerCards、setDueDate、changeDeck。
• カード/ノートを実質的に変更するデッキまたはモデルの変更（デッキ削除、モデル編集）。上記に明示されていなくても質問してください。

API の基本

リクエスト形式

すべてのリクエストは以下を含む JSON です：

• action：文字列アクション名
• version：API バージョン（ユーザーが別途指定しない限り 6 を使用）
• params：パラメータのオブジェクト（オプション）

レスポンス形式

すべてのレスポンスは以下を含む JSON です：

• result：戻り値
• error：成功時は null またはエラーを説明する文字列

result を使用する前に必ず error を確認してください。

パーミッション

• 信頼されていないオリジンからやり取りする場合、最初に requestPermission を使用してください。これはあらゆるオリジンを受け入れる唯一のアクションです。
• version を使用して互換性を確保してください。古いバージョンでは version ≤ 4 の場合、レスポンス内の error フィールドが省略されることがあります。

curl + jq パターン

JSON を構築し、レスポンスを解析するには jq を優先します。リクエストは明示的で構造化された状態に保ちます。

最小限のリクエストテンプレート

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 @-

パラメータ付き

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 @-

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'

複数アクションのバッチ処理

multi を使用して往復を減らし、データ修正時にアクションを単一の確認でグループ化します。

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 @-

チェーン処理時に前のアクションの結果で空の配列を置き換えてください。CLI 使用時には、スクリプト言語を使用しない限り 2 つの呼び出しに分割します。

コアワークフロー ガイダンス

1) 接続性とバージョンの確認

• requestPermission を呼び出します（安全）。
• version を呼び出して API レベルを確認し、リクエストで version: 6 を使用します。

2) サポートされているアクションを検出

• apiReflect を scopes: ["actions"] で使用して、サポートされているアクションをリストアップします。
• このリストを使用してユーザーの意図をアクション名にマッピングします。

3) ユーザーリクエストをアクションシーケンスに解決

• 読み取り専用と破壊的な操作を識別します。
• ノート/カードに対する破壊的/変更操作については、スコープと数を一度確認します。
• 変更前のプレビューのため、findNotes/findCards + notesInfo/cardsInfo を優先します。

4) 実行と検証

• 順番に呼び出しを実行します。
• 各レスポンスで error を確認します。
• 集計された結果と返された ID を報告します。

一般的なタスク レシピ（CLI 指向）

デッキをリストアップ

• アクション：deckNames

デッキを作成

• アクション：createDeck
• デッキがカード/ノート変更ワークフローの一部として作成される場合、確認が必要です。

ノート/カードを検索

• アクション：findNotes、findCards
• Anki 検索構文を使用します（以下の「検索構文クイックノート」を参照）。

ノートデータをプレビュー

• アクション：notesInfo（ノート ID）

ノートを追加

• アクション：addNote、addNotes
• 確認が必要です。
• プリフライトチェックには canAddNotes または canAddNotesWithErrorDetail を使用します。

ノートのフィールドまたはタグを更新

• アクション：updateNoteFields、updateNoteTags、または統合 updateNote
• 確認が必要です。
• 警告：ブラウザでノートを開かないでください。更新が適用されない場合があります。

ノートを削除

• アクション：deleteNotes
• 確認が必要です。

カードをサスペンド/サスペンド解除

• アクション：suspend、unsuspend
• 確認が必要です。

カードをデッキに移動

• アクション：changeDeck
• 確認が必要です。

期日を設定またはリスケジュール

• アクション：setDueDate
• 確認が必要です。

メディア アップロード/ダウンロード

• アクション：storeMediaFile、retrieveMediaFile、getMediaFilesNames、getMediaDirPath、deleteMediaFile
• アップロードには base64（data）、ファイルパス（path）、または URL（url）を使用します。

同期

• アクション：sync

検索構文クイックノート（findNotes/findCards 用）

• 複数の語句をスペースで区切ります。デフォルトで語句は AND でつながります。
• NOT ロジックのために or、括弧、- を使用します。
• deck:Name、tag:tagname、note:ModelName、card:CardName を使用します。
• front:... または他のフィールド名を使用して、フィールドで制限します。
• re: は正規表現用、w: は単語境界検索用、nc: はアクセント無視用です。
• is:due、is:new、is:learn、is:review、is:suspended、is:buried を使用してカードの状態でフィルタリングします。
• interval や期日などのプロパティについては prop: 検索を使用します。
• 必要に応じてクォートまたはバックスラッシュで特殊文字をエスケープします。

アクション カタログ（マッピング リファレンスとして使用）

カード アクション

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

デッキ アクション

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

グラフィカル アクション

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

メディア アクション

• storeMediaFile
• retrieveMediaFile
• getMediaFilesNames
• getMediaDirPath
• deleteMediaFile

その他のアクション

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

モデル アクション

• 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

ノート アクション

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

統計 アクション

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

注意と落とし穴

• macOS では Anki をフォアグラウンドに保つか、App Nap を無効にして AnkiConnect が一時停止しないようにします。
• ノートを更新する場合、ブラウザエディタで表示されていないことを確認してください。更新が適用されない場合があります。
• importPackage パスはクライアントではなく、Anki collection.media フォルダに相対的です。
• deleteDecks ではデッキに沿ってカードも削除するために cardsToo: true が必要です。

リソース

このスキルに必要なバンドルされたスクリプトやアセットはありません。